hybrid_platforms_conductor 32.12.0 → 32.13.0

data/docs/config_dsl.md

@@ -0,0 +1,315 @@
+# Configuration DSL
+
+The DSL used in configuration files is comprised of Ruby methods that can be called directly in the main `hpc_config.rb` file.
+
+This DSL can also be completed by plugins. Check [the plugins documentations](plugins) to know about DSL extensions brought by plugins.
+
+# Table of Contents
+  * [`<platform_type>_platform`](#platform_type_platform)
+  * [`include_config_from`](#include_config_from)
+  * [`os_image`](#os_image)
+  * [`deployment_schedule`](#deployment_schedule)
+  * [`for_nodes`](#for_nodes)
+  * [`hybrid_platforms_dir`](#hybrid_platforms_dir)
+  * [`tests_provisioner`](#tests_provisioner)
+  * [`expect_tests_to_fail`](#expect_tests_to_fail)
+  * [`retry_deploy_for_errors_on_stdout`](#retry_deploy_for_errors_on_stdout)
+  * [`retry_deploy_for_errors_on_stderr`](#retry_deploy_for_errors_on_stderr)
+  * [`packaging_timeout`](#packaging_timeout)
+  * [`master_cmdbs`](#master_cmdbs)
+  * [`sudo_for`](#sudo_for)
+
+<a name="platform_type_platform"></a>
+## `<platform_type>_platform`
+
+Declare a new platform of type `<platform_type>`, providing either a local path to it (using `path: '/path/to/files'`) or a git repository to it (using `git: 'git_url'`). The possible platform types are the names of the [`platform_handler` plugins](plugins.md#platform_handler).
+
+Git branches can also be specified using `branch: 'branch_name'`.
+An optional code block taking the local repository path as parameter can also be specified to add configuration that is specific to this platform.
+
+Examples:
+```ruby
+# Declare a platform of type Chef, located in a distant git repository
+chef_platform git: 'https://my-git.domain.com/project/my-chef-repo.git'
+
+# Declare a platform located in a local path
+chef_platform path: '/path/to/my-chef-repo'
+
+# Declare a platform from a git branch, and apply some configuration to it
+chef_platform(
+  git: 'https://my-git.domain.com/project/my-chef-repo.git',
+  branch: 'my-branch'
+) do |path|
+  # Here path will be a local path containing a checkout of the branch my-branch of the git repo.
+
+  # We can use that to check for the repo itself before using it.
+  raise 'Missing Chef file' unless File.exist?("#{path}/solo.rb")
+
+  # And we can use other DSL methods that would apply only to this platform
+  expect_tests_to_fail [:idempotence], 'Idempotence tests should fail for nodes belonging to this platform'
+end
+```
+
+<a name="include_config_from"></a>
+## `include_config_from`
+
+Include another DSL configuration file.
+Takes the file path as parameter.
+Useful to better organize your configuration files, and move the platform-specific configuration files within platform repositories to avoid having dependencies between your repositories.
+
+Examples:
+```ruby
+# Include a global config file
+include_config_from './my_confs/security.rb'
+
+chef_platform(git: 'https://my-git.domain.com/project/my-chef-repo.git') do |path|
+  # Include a config file in a platform repository
+  include_config_from "#{path}/chef-config.rb"
+end
+```
+
+<a name="os_image"></a>
+## `os_image`
+
+Declare a new OS image, with its corresponding path.
+
+An OS image can be used by some processes to adapt to differences based on OS (for example Windows, Debian, CentOS 7, CentOS 8...).
+Example of usages:
+* Get a Dockerfile test image
+* Install packages differently (`apt`, `yum`...)
+
+Any node from any platform can define its OS using the `image` metadata. This should be a name referenced using this DSL.
+
+`os_image` takes 2 parameters: its name (as a Symbol) and its directory path (as a String).
+
+Examples:
+```ruby
+os_image :centos_7, '/path/to/images/centos_7'
+# Here we should have a Dockerfile /path/to/images/centos_7/Dockerfile for any Docker-based process that needs a test image to be provisioned.
+# Any node having the image metadata set to centos_7 will use this Dockerfile.
+```
+
+<a name="deployment_schedule"></a>
+## `deployment_schedule`
+
+The `deployment_schedule` method defines a schedule to be applied for regular nodes deployment. This schedule is then used by the [`nodes_to_deploy` executable](executables/nodes_to_deploy.md) to know which nodes should be deployed at a given time.
+Takes an [`IceCube::Schedule` object](https://github.com/seejohnrun/ice_cube) as raw parameter but the configuration DSL lets you use some helpers that generate those objects for you:
+* **`daily_at`**: This helper generates a daily schedule. It takes the following parameters:
+  * **time** (`String`): Parsable UTC time (like '14:10:50') at which the schedule starts.
+  * **duration** (`Integer`): Number of seconds for the schedule duration [default: 3000].
+* **`weekly_at`**: This helper generates a weekly schedule. It takes the following parameters:
+  * **days** (`Symbol` or `Array<Symbol>`): Day name (or list of day names) on which the schedule applies. See [IceCube documentation](https://github.com/seejohnrun/ice_cube) for precise day names (`:monday`, `:tuesday`...).
+  * **time** (`String`): Parsable UTC time (like '14:10:50') at which the schedule starts.
+  * **duration** (`Integer`): Number of seconds for the schedule duration [default: 3000].
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+# Deploy everything every day at 4am
+deployment_schedule(daily_at('04:00:00'))
+
+# And also deploy production every week on sundays during the morning only (4 hours starting at 8am)
+for_nodes('/prd/') do
+  deployment_schedule(weekly_at(:sunday, '08:00:00', duration: 4 * 3600))
+end
+```
+
+<a name="for_nodes"></a>
+## `for_nodes`
+
+The `for_nodes` lets you open a scope in the configuration in which DSL methods apply to a subset of nodes. Scopes can be stacked, and always restrict the nodes it applies to, by doing intersection of the stacking subsets.
+Takes a list of nodes selectors as parameter. Each nodes selector can be the following:
+* `String`: Node name, or a node regexp if enclosed within '/' character (ex: `'/.+worker.+/'`)
+* `Hash<Symbol,Object>`: More complete information that can contain the following keys:
+  * **all** (`Boolean`): If true, specify that we want all known nodes.
+  * **list** (`String`): Name of a nodes list.
+  * **platform** (`String`): Name of a platform containing nodes.
+  * **service** (`String`): Name of a service implemented by nodes.
+  * **git_diff** (`Hash<Symbol,Object>`): Info about a git diff that impacts nodes:
+    * **platform** (`String`): Name of the platform on which checking the git diff
+    * **from_commit** (`String`): Commit ID to check from [default: 'master']
+    * **to_commit** (`String` or `nil`): Commit ID to check to, or nil for currently checked-out files [default: nil]
+    * **smallest_set** (`Boolean`): Smallest set of impacted nodes? [default: false]
+
+Examples:
+```ruby
+# Set deployment schedule of test nodes at 4am
+for_nodes('/tst.*/') do
+  deployment_schedule(daily_at('04:00:00'))
+end
+
+# Set deployment schedule of nodes implementing the firewall and web_server services at 5am
+for_nodes [
+  { service: 'firewall' },
+  { service: 'web_server' }
+] do
+  deployment_schedule(daily_at('05:00:00'))
+  # Among them make sure the main firewall node is redeployed at 6am
+  for_nodes('prd-main-firewall') do
+    deployment_schedule(daily_at('06:00:00'))
+  end
+end
+```
+
+<a name="hybrid_platforms_dir"></a>
+## `hybrid_platforms_dir`
+
+Get the directory in which the `hpc_config.rb` file is stored.
+
+This can be useful in case the configuration needs to access files based on the main configuration path.
+
+Examples:
+```ruby
+# We have our images paths in the same directory storing hpc_config.rb
+os_image :centos_7, "#{hybrid_platforms_dir}/images/centos_7"
+```
+
+<a name="tests_provisioner"></a>
+## `tests_provisioner`
+
+Specify which provisioner should be used when tests need to provision a test container.
+Takes a Symbol as parameter, being the name of the provisioner.
+Possible values are names of [`provisioner` plugins](plugins.md#provisioner). Defaults to `docker`.
+
+Examples:
+```ruby
+# For our test containers we rely on a Proxmox cluster
+tests_provisioner :proxmox
+```
+
+<a name="expect_tests_to_fail"></a>
+## `expect_tests_to_fail`
+
+Inform the tests reports that some tests are expected to be failing.
+This can be useful when tests are failing for temporary reasons or when technical debt is accumulating but we still want to track it.
+Takes 2 parameters:
+* **tests** (`Symbol` or `Array<Symbol>`): Test name (or list of test names) that are expected to fail. Names are [`test` plugins](plugins.md#test)'s names.
+* **reason** (`String`): Descriptive reason for the expected failure. Used in logging only.
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+# Bitbucket is currently down, so tests are failing
+expect_tests_to_fail :bitbucket_conf, 'Our Bitbucket server is down.'
+
+# Test nodes are not yet patched against Spectre variants
+for_nodes('/tst/') do
+  expect_tests_to_fail :spectre, 'Test nodes are not patched yet. See ticket PRJ-455'
+end
+```
+
+<a name="retry_deploy_for_errors_on_stdout"></a>
+## `retry_deploy_for_errors_on_stdout`
+
+`retry_deploy_for_errors_on_stdout` lets you define some rules matching deployment logs to detect non-deterministic errors that can be retried.
+It can happen that deployment fails for an undeterministic reason (network hickups, DNS temporarily down...) and you want to retry it. In this case this method lets you define some pattern-matching rules on a failed deployment stdout that if matched will trigger a subsequent deployment.
+Takes a list of (or a single) rules as parameter. Each rule can be:
+* `String`: An exact match
+* `Regexp`: A regular expression match
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+# When Ansible fails because of SSH hickups, retry
+retry_deploy_for_errors_on_stdout(/FAILED: .* SSH connection failed/)
+
+# Test nodes have sometimes DNS issues
+for_nodes('/tst/') do
+  retry_deploy_for_errors_on_stdout [
+    'DNS resolution failed',
+    'DNS unknown error',
+    /Unable to query DNS server .*/
+  ]
+end
+```
+
+<a name="retry_deploy_for_errors_on_stderr"></a>
+## `retry_deploy_for_errors_on_stderr`
+
+`retry_deploy_for_errors_on_stderr` lets you define some rules matching deployment logs from stderr to detect non-deterministic errors that can be retried.
+It can happen that deployment fails for an undeterministic reason (network hickups, DNS temporarily down...) and you want to retry it. In this case this method lets you define some pattern-matching rules on a failed deployment stdout that if matched will trigger a subsequent deployment.
+Takes a list of (or a single) rules as parameter. Each rule can be:
+* `String`: An exact match
+* `Regexp`: A regular expression match
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+# When Ansible fails because of SSH hickups, retry
+retry_deploy_for_errors_on_stderr(/FAILED: .* SSH connection failed/)
+
+# Test nodes have sometimes DNS issues
+for_nodes('/tst/') do
+  retry_deploy_for_errors_on_stderr [
+    'DNS resolution failed',
+    'DNS unknown error',
+    /Unable to query DNS server .*/
+  ]
+end
+```
+
+<a name="packaging_timeout"></a>
+## `packaging_timeout`
+
+`packaging_timeout` defines the timeout to package a platform during deployment. Defaults to 60.
+Takes the timeout (in seconds) as an `Integer` parameter.
+
+Examples:
+```ruby
+# Some packaging are downloading a lot of stuff for a few minutes, so timeout after 10 minutes.
+packaging_timeout 600
+```
+
+<a name="master_cmdbs"></a>
+## `master_cmdbs`
+
+`master_cmdbs` is a method that helps in resolving metadata conflicts between different CMDB.
+Depending on the context and environments, some metadata conflicts might be unacceptable (like IP conflicts) and others might be mergeable (like services definitions).
+`master_cmdbs` takes a hash of CMDB names (taken as names of [`cmdb` plugins](plugins.md#cmdb)), and the corresponding metadata identifiers (as `Array<Symbol>` or `Symbol`) for which this CMDB is considered the authority in case of conflicts.
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+master_cmdbs(
+  # The host_ip CMDB is the authority to discover host IPs - don't rely on other sources like config or platforms inventory.
+  host_ip: :host_ip,
+  # The platform_handler CMDB is the authority to discover nodes description and OS images
+  platform_handler: %i[description image]
+)
+```
+
+<a name="sudo_for"></a>
+## `sudo_for`
+
+`sudo_for` provides a way to transform sudo commands for some nodes or users.
+This is useful to adapt on environments on which the escalation of privileges is not as simple as using `sudo <cmd>`, or when `root` is not accessible via `sudo`.
+This is used by any Hybrid Platforms Conductor process that needs to perform some [`remote_bash` actions](plugins/action/remote_bash.md) using sudo.
+Takes a code block as parameter that has the following signature:
+* Parameters:
+  * **user** (`String`): User for which we want sudo
+* Result:
+  * `String`: Corresponding sudo string
+
+Can be applied to subset of nodes using the [`for_nodes` DSL method](#for_nodes).
+
+Examples:
+```ruby
+sudo_for do |user|
+  # Production users have to first sudo through a service user associated to them to gain root privilege
+  if user =~ /^prd_(.*)/
+    "sudo -u svc_#{$1} sudo"
+  else
+    'sudo'
+  end
+end
+
+# Our gateways have a sudo alias
+for_nodes({ service: 'gateway' }) do
+  sudo_for { |_user| 'aliased_sudo' }
+end
+```

data/docs/executables.md

@@ -0,0 +1,226 @@
+# Executables
+
+Here is the list of executables that come bundled with the Hybrid Platforms Conductor, along with their description.
+
+You can check the common command line options [at the end of this document](#common_options).
+
+# Table of Contents
+  * [`report`](executables/report.md)
+  * [`run`](executables/run.md)
+  * [`check-node`](executables/check-node.md)
+  * [`deploy`](executables/deploy.md)
+  * [`ssh_config`](executables/ssh_config.md)
+  * [`nodes_to_deploy`](executables/nodes_to_deploy.md)
+  * [`last_deploys`](executables/last_deploys.md)
+  * [`get_impacted_nodes`](executables/get_impacted_nodes.md)
+  * [`test`](executables/test.md)
+  * [`setup`](executables/setup.md)
+  * [`free_ips`](executables/free_ips.md)
+  * [`free_veids`](executables/free_veids.md)
+  * [`dump_nodes_json`](executables/dump_nodes_json.md)
+  * [`topograph`](executables/topograph.md)
+  * [Common options](#common_options)
+
+<a name="common_options"></a>
+# Common command line options
+
+Most of the tools share a set of common command line options. The shared command line options are grouped by functionality the tool is using.
+This section lists them all and how they affect the tools' behaviour.
+
+## Nodes Handler options
+
+The nodes handler options add functionality about nodes information.
+
+```
+Nodes handler options:
+    -o, --show-nodes                 Display the list of possible nodes and exit
+```
+
+* `--show-nodes`: Display the list of known nodes, nodes lists, platforms, services, description... and exit.
+
+The following metadata is being used to display nodes' information:
+
+| Metadata | Type | Usage
+| --- | --- | --- |
+| `description` | `String` | Node's description |
+| `host_ip` | `String` | Node's IP |
+| `hostname` | `String` | Node's hostname |
+| `private_ips` | `Array<String>` | List of a node's private IPs |
+| `services` | `Array<String>` | List of services attached to a node |
+
+## Nodes selection options
+
+The nodes selection options are used to select a set of nodes that the tool needs as input.
+
+```
+Nodes selection options:
+    -a, --all-nodes                  Select all nodes
+    -b, --nodes-platform PLATFORM    Select nodes belonging to a given platform name. Available platforms are: ansible-repo, chef-repo (can be used several times)
+    -l, --nodes-list LIST            Select nodes defined in a nodes list (can be used several times)
+    -n, --node NODE                  Select a specific node. Can be a regular expression to select several nodes if used with enclosing "/" characters. (can be used several times).
+    -r, --nodes-service SERVICE      Select nodes implementing a given service (can be used several times)
+        --nodes-git-impact GIT_IMPACT
+                                     Select nodes impacted by a git diff from a platform (can be used several times).
+                                     GIT_IMPACT has the format PLATFORM:FROM_COMMIT:TO_COMMIT:FLAGS
+                                     * PLATFORM: Name of the platform to check git diff from. Available platforms are: ansible-repo, chef-repo
+                                     * FROM_COMMIT: Commit ID or refspec from which we perform the diff. If ommitted, defaults to master
+                                     * TO_COMMIT: Commit ID ot refspec to which we perform the diff. If ommitted, defaults to the currently checked-out files
+                                     * FLAGS: Extra comma-separated flags. The following flags are supported:
+                                       - min: If specified then each impacted service will select only 1 node implementing this service. If not specified then all nodes implementing the impacted services will be selected.
+```
+
+* `--all-nodes`: Select all the known nodes.
+* `--nodes-platform PLATFORM`: Specify the name of a platform as a selector. Can be useful to only perform checks of nodes of a given repository after merging a PR on this repository.
+* `--nodes-list LIST`: Specify a hosts list name as selector. Hosts list are a named group of hosts, and are defined by each platform if they make sense. For example all the nodes belonging to the same cluster could be part of a nodes list.
+* `--node NODE`: Select a single node. A regular expression can also be used when `NODE` is enclosed with `/` character (the regular expression grammar is [the Ruby one](http://ruby-doc.org/core-2.5.0/Regexp.html)). Examples: `--node my_node_1`, `--node /my_node_.+/`.
+* `--nodes-service SERVICE`: Select all nodes that implement a given service.
+* `--nodes-git-impact GIT_IMPACT`: Select nodes that are impacted by a git diff on a platform. 2 commit ids or refspecs can be specified for the diff. Examples: `--nodes-git-impact chef-repo::my_branch` will select all nodes that are impacted by the diffs made between `my_branch` and `master` on the git repository belong to the `chef-repo` platform.
+
+The following metadata is being used by some selectors:
+
+| Metadata | Type | Usage
+| --- | --- | --- |
+| `services` | `Array<String>` | List of services attached to a node, used to retrieve nodes selected by a service |
+
+## Command Runner options
+
+The Command Runner options are used to drive how commands are executed.
+
+```
+Command runner options:
+    -s, --show-commands              Display the commands that would be run instead of running them
+```
+
+* `--show-commands`: Display the commands the tool would execute, without executing them. Useful to understand or debug the tool's behaviour.
+
+## Actions Executor options
+
+The Actions Executor options are used to drive how actions are executed.
+
+```
+Actions Executor options:
+    -m, --max-threads NBR            Set the number of threads to use for concurrent queries (defaults to 16)
+```
+
+* `--max-threads NBR`: Specify the maximal number of threads to use when concurrent execution is performed.
+
+## Connector SSH options
+
+The SSH connector options are used to drive how SSH connections are handled.
+
+```
+Connector ssh options:
+    -g, --ssh-gateway-user USER      Name of the gateway user to be used by the gateways. Can also be set from environment variable hpc_ssh_gateway_user. Defaults to ubradm.
+    -j, --ssh-no-control-master      If used, don't create SSH control masters for connections.
+    -q, --ssh-no-host-key-checking   If used, don't check for SSH host keys.
+    -u, --ssh-user USER              Name of user to be used in SSH connections (defaults to hpc_ssh_user or USER environment variables)
+    -w, --password                   If used, then expect SSH connections to ask for a password.
+    -y GATEWAYS_CONF,                Name of the gateways configuration to be used. Can also be set from environment variable hpc_ssh_gateways_conf.
+        --ssh-gateways-conf
+```
+
+* `--ssh-gateway-user USER`: Specify the user to be used through the gateway accessing the nodes.
+* `--ssh-no-control-master`: If specified, don't use an SSH control master: it will open/close an SSH connection for every command it needs to run.
+* `--ssh-no-host-key-checking`: If specified, make sure SSH connections don't check for host keys.
+* `--ssh-user USER`: Specify the user to be used on the node being accessed by the tool. It is recommended to set the default value of this option in the `hpc_ssh_user` environment variable. If both this option and the `hpc_ssh_user` variables are omitted, then the `USER` environment variable is used.
+* `--password`: When specified, then don't use `-o BatchMode=yes` on SSH commands so that if connection needs a password it will be asked. Useful to deploy on accounts not having key authentication yet.
+* `--ssh-gateways-conf GATEWAYS_CONF`: Specify the gateway configuration name to be used. Gateway configurations are defined in the platforms definition file (`./hpc_config.rb`). It is recommended to set the default value of this option in the `hpc_ssh_gateways_conf` environment variable.
+
+## Deployer options
+
+The Deployer options are used to drive a deployment (be it in why-run mode or not).
+
+```
+Deployer options:
+    -e, --secrets SECRETS_LOCATION   Specify a secrets location. Can be specified several times. Location can be:
+                                     * Local path to a JSON file
+                                     * URL of the form http[s]://<url>:<secret_id> to get a secret JSON file from a Thycotic Secret Server at the given URL.
+    -p, --parallel                   Execute the commands in parallel (put the standard output in files <hybrid-platforms-dir>/run_logs/*.stdout)
+    -t, --timeout SECS               Timeout in seconds to wait for each chef run. Only used in why-run mode. (defaults to no timeout)
+    -W, --why-run                    Use the why-run mode to see what would be the result of the deploy instead of deploying it for real.
+        --retries-on-error NBR       Number of retries in case of non-deterministic errors (defaults to 0)
+```
+
+* `--secrets SECRETS_LOCATION`: Specify a JSON file storing secrets that can be used by the deployment process. Secrets are values that are needed for deployment but that should not be part of the platforms repositories (such as passwords, API keys, SSL certificates...).
+  The location can be:
+  * A local file path (for example /path/to/file.json).
+  * A Thycotic Secret Server URL followed by a secret id (for example https://portal.muc.msp.my_company.net/SecretServer:8845).
+* `--parallel`: Specify that the deployment process should perform concurrently on the different nodes it has to deploy to.
+* `--timeout SECS`: Specify the timeout (in seconds) to apply while deploying. This can be set only in why-run mode.
+* `--why-run`: Specify the why-run mode. The why-run mode is used to simulate a deployment on the nodes, and report what a real deployment would have changed on the node.
+* `--retries-on-error NBR`: Specify the number of retries deploys can do in case of non-deterministic errors.
+  Non-deterministic errors are matched using a set of strings or regular expressions that can be configured in the `hpc_config.rb` file of any platform, using the `retry_deploy_for_errors_on_stdout` and `retry_deploy_for_errors_on_stderr` properties:
+  For example:
+```ruby
+retry_deploy_for_errors_on_stdout [
+  'This is a raw string error that will be matched against stdout',
+  /This is a regexp match ending with.* error/
+]
+retry_deploy_for_errors_on_stderr [
+  'This is a raw string error that will be matched against stderr'
+]
+```
+
+## JSON dump options
+
+The JSON dump options drive the way nodes' JSON information is being dumped.
+
+```
+JSON dump options:
+    -k, --skip-run                   Skip the actual gathering of dumps in run_logs. If set, the current run_logs content will be used.
+    -j, --json-dir DIRECTORY         Specify the output directory in which JSON files are being written. Defaults to nodes_json.
+```
+
+* `--skip-run`: Don't fetch the information from the nodes themselves, but use the previous output from the `run_logs` directory. Useful if executing the command several times.
+* `--json-dir DIRECTORY`: Specify the name of the directory where JSON files will be written.
+
+## Topographer options
+
+The Topographer options drive the way the topographer works. The Topographer is used to manipulate and dump the topology off the platforms.
+
+```
+Topographer options:
+    -F, --from HOSTS_OPTIONS         Specify options for the set of nodes to start from (enclose them with ""). Default: all nodes. HOSTS_OPTIONS follows the following:
+                                         -a, --all-nodes                  Select all nodes
+                                         -b, --nodes-platform PLATFORM    Select nodes belonging to a given platform name. Available platforms are: ansible-repo, chef-repo (can be used several times)
+                                         -l, --nodes-list LIST            Select hosts defined in a nodes list (can be used several times)
+                                         -n, --node NODE                  Select a specific node. Can be a regular expression to select several nodes if used with enclosing "/" characters. (can be used several times).
+    -k, --skip-run                   Skip the actual gathering of JSON node files. If set, the current files in nodes_json will be used.
+    -p, --output FORMAT:FILE_NAME    Specify a format and file name. Can be used several times. FORMAT can be one of graphviz, json, svg. Ex.: graphviz:graph.gv
+    -T, --to HOSTS_OPTIONS           Specify options for the set of nodes to get to (enclose them with ""). Default: all nodes. HOSTS_OPTIONS follows the following:
+                                         -a, --all-nodes                  Select all nodes
+                                         -b, --nodes-platform PLATFORM    Select nodes belonging to a given platform name. Available platforms are: ansible-repo, chef-repo (can be used several times)
+                                         -l, --nodes-list LIST            Select hosts defined in a nodes list (can be used several times)
+                                         -n, --node NODE                  Select a specific node. Can be a regular expression to select several nodes if used with enclosing "/" characters. (can be used several times).
+```
+
+* `--from HOSTS_OPTIONS`: Specify the set of source nodes that we want to graph from.
+* `--skip-run`: Don't fetch the information from the nodes themselves, but use the previous output from the `nodes_json` directory (that can be used as an output of the `dump_nodes_json` tool). Useful if executing the command several times.
+* `--output FORMAT:FILE_NAME`: Specify the format and file name in which we want to output the topology graph.
+* `--to HOSTS_OPTIONS`: Specify the set of destination nodes that we want to graph to.
+
+## Test Runner options
+
+Test Runner options are used to drive the running of tests.
+
+```
+Tests runner options:
+    -i, --tests-list FILE_NAME       Specify a tests file name. The file should contain a list of tests name (1 per line). Can be used several times.
+    -k, --skip-run                   Skip running the check-node commands for real, and just analyze existing run logs.
+    -r, --report REPORT              Specify a report name. Can be used several times. Can be all for all reports. Possible values: confluence, stdout (defaults to stdout).
+    -t, --test TEST                  Specify a test name. Can be used several times. Can be all for all tests. Possible values: ansible_repo_molecule_cdh_admins, ansible_repo_molecule_cdh_datanodes, ansible_repo_molecule_cdh_db, ansible_repo_molecule_cdh_gateways, ansible_repo_molecule_cdh_services, ansible_repo_molecule_common, ansible_repo_molecule_data_gateway, ansible_repo_molecule_dev_servers, ansible_repo_molecule_ds_servers, ansible_repo_molecule_dsnodes, ansible_repo_molecule_import_gateway, ansible_repo_molecule_notebooks, ansible_repo_molecule_tnz_data_gateway, bitbucket_conf, can_be_checked, check_from_scratch, chef_executables, chef_success, chef_woulds, connection, deploy_freshness, deploy_from_scratch, deploy_removes_root_access, executables, food_critic, group_ids, hostname, idempotence, ip, jenkins_ci_conf, jenkins_ci_masters_ok, linear_strategy, obsolete_home_dirs, obsolete_users, orphan_files, private_ips, public_ips, rubocop, spectre, unused_files, unused_node_attributes, unused_recipes, unused_templates, unused_roles, unused_users, user_ids, users_without_roles, veids (defaults to all).
+        --max-threads-connections NBR_THREADS
+                                     Specify the max number of threads to parallelize tests connecting on nodes (defaults to 64).
+        --max-threads-nodes NBR_THREADS
+                                     Specify the max number of threads to parallelize tests at node level (defaults to 8).
+        --max-threads-platforms NBR_THREADS
+                                     Specify the max number of threads to parallelize tests at platform level (defaults to 8).
+```
+
+* `--report REPORT_NAME`: Specify which report plugin to use.
+* `--skip-run`: Don't fetch the information from the nodes themselves, but use the previous output from the `run_logs` directory. Useful if executing the command several times.
+* `--test TEST_NAME`: Specify the test to be performed.
+* `--tests-list FILE_NAME`: Give a file containing a list of tests names. The file can also containg comment lines starting with `#`.
+* `--max-threads-connections NBR_THREADS`: Make sure that there won't be more than `NBR_THREADS` simultaneous connections to nodes.
+* `--max-threads-nodes NBR_THREADS`: Make sure that there won't be more than `NBR_THREADS` simultaneous tests run in parallel at node level. Those include Docker tests.
+* `--max-threads-platforms NBR_THREADS`: Make sure that there won't be more than `NBR_THREADS` simultaneous tests run in parallel at platform level. Those include Molecule, linter tests...