Command Line Interface¶
Category: db¶
CLI commands for DB management.
rally db create¶
Create Rally database.
rally db ensure¶
Creates Rally database if it doesn’t exists.
rally db revision¶
Print current Rally database revision UUID.
rally db show¶
Show the connection string.
Command arguments:
–creds [ref]
Do not hide credentials from connection string
rally db upgrade¶
Upgrade Rally database to the latest state.
Category: deployment¶
Set of commands that allow you to manage deployments.
rally deployment check¶
Check all credentials and list all available services.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of the deployment.
type: str
rally deployment config¶
Display configuration of the deployment.
Output is the configuration of the deployment in a pretty-printed JSON format.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of the deployment.
type: str
rally deployment create¶
Create new deployment.
This command will create a new deployment record in rally database. In the case of ExistingCloud deployment engine, it will use the cloud represented in the configuration. If the cloud doesn’t exist, Rally can deploy a new one for you with Devstack or Fuel. Different deployment engines exist for these cases (see rally plugin list –plugin-base Engine for more details).
If you use the ExistingCloud deployment engine, you can pass
the deployment config by environment variables with --fromenv:
OS_USERNAME OS_PASSWORD OS_AUTH_URL OS_TENANT_NAME or OS_PROJECT_NAME OS_ENDPOINT_TYPE or OS_INTERFACE OS_ENDPOINT OS_REGION_NAME OS_CACERT OS_INSECURE OS_IDENTITY_API_VERSION
All other deployment engines need more complex configuration data, so it should be stored in a configuration file.
You can use physical servers, LXC containers, KVM virtual machines or virtual machines in OpenStack for deploying the cloud. Except physical servers, Rally can create cluster nodes for you. Interaction with virtualization software, OpenStack cloud or physical servers is provided by server providers.
Command arguments:
–name <name> [ref]
Name of the deployment.
type: str
–fromenv [ref]
Read environment variables instead of config file.
–filename <path> [ref]
Path to the configuration file of the deployment.
type: str
default: none
–no-use [ref]
Don’t set new deployment as default for future operations.
rally deployment destroy¶
Destroy existing deployment.
This will delete all containers, virtual machines, OpenStack instances or Fuel clusters created during Rally deployment creation. Also it will remove the deployment record from the Rally database.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of the deployment.
type: str
rally deployment list¶
List existing deployments.
rally deployment recreate¶
Destroy and create an existing deployment.
Unlike ‘deployment destroy’, the deployment database record will not be deleted, so the deployment UUID stays the same.
Command arguments:
–filename <path> [ref]
Path to the configuration file of the deployment.
type: str
default: none
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of the deployment.
type: str
rally deployment show¶
Show the credentials of the deployment.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of the deployment.
type: str
Category: env¶
Set of commands that allow you to manage envs.
rally env check¶
Check availability of all platforms in environment.
Command arguments:
–env <uuid> [ref]
UUID or name of the env.
type: str
default: none
–json [ref]
Format output as JSON.
–detailed [ref]
Show detailed information.
rally env cleanup¶
Perform disaster cleanup for specified environment.
Cases when Rally can leave undeleted resources after performing workload:
Rally execution was interrupted and cleanup was not performed
The environment or a particular platform became unreachable which fail Rally execution of cleanup
Command arguments:
–json [ref]
Format output as JSON.
–env <uuid> [ref]
UUID or name of the env.
type: str
default: none
rally env create¶
Create new environment.
Command arguments:
–name <name>, -n <name> [ref]
Name of the env.
type: str
–description <description>, -d <description> [ref]
Env description
type: str
default: none
–extras <extras>, -e <extras> [ref]
JSON or YAML dict with custom non validate info.
type: str
default: none
–from-sysenv [ref]
Iterate over all available platforms and check system environment for credentials.
–spec <path>, -s <path> [ref]
Path to env spec.
type: str
default: none
–json [ref]
Format output as JSON.
–no-use [ref]
Don’t set new env as default for future operations.
rally env delete¶
Deletes all records related to the environment from db.
Command arguments:
–env <uuid> [ref]
UUID or name of the env.
type: str
default: none
–force [ref]
Delete DB records even if env is not destroyed.
rally env destroy¶
Destroy existing environment.
Command arguments:
–env <uuid> [ref]
UUID or name of the env.
type: str
default: none
–skip-cleanup [ref]
Do not perform platforms cleanup before destroy.
–json [ref]
Format output as JSON.
–detailed [ref]
Show detailed information.
rally env info¶
Retrieve and show environment information.
Command arguments:
–env <uuid> [ref]
UUID or name of the env.
type: str
default: none
–json [ref]
Format output as JSON.
Category: plugin¶
Set of commands that allow you to manage Rally plugins.
rally plugin list¶
List all Rally plugins that match name and platform.
Command arguments:
–name <name> [ref]
List only plugins that match the given name.
type: str
default: none
–platform <platform> [ref]
List only plugins that are in the specified platform.
type: str
default: none
–plugin-base <plugin_base> [ref]
Plugin base class.
type: str
default: none
Category: task¶
Set of commands that allow you to manage tasks and results.
rally task abort¶
Abort a running task.
Command arguments:
–uuid <uuid> [ref]
UUID of task.
type: str
–soft [ref]
Abort task after current scenario finishes execution.
rally task delete¶
Delete task and its results.
Command arguments:
–force [ref]
Force delete
–uuid <task-id> [ref]
UUID of task or a list of task UUIDs.
type: str
rally task detailed¶
Command arguments:
–uuid <uuid> [ref]
UUID of task. If –uuid is “last” the results of the most recently created task will be displayed.
type: str
–iterations-data [ref]
Print detailed results for each iteration.
–filter-by <filter_by> [ref]
Filter the displayed workloads.<sla-failures>: only display the failed workloads.
type: str
default: none
rally task export¶
Export task results to the custom task’s exporting system.
Command arguments:
–uuid <uuid> [ref]
UUIDs of tasks or json reports of tasks
type: str
default: none
–type <type> [ref]
Report type. Out-of-the-box types: JSON, HTML, HTML-Static, Elastic, JUnit-XML. HINT: You can list all types, executing rally plugin list –plugin-base TaskExporter command.
type: str
default: none
–to <dest> [ref]
Report destination. Can be a path to a file (in case of JSON, HTML, HTML-Static, JUnit-XML, Elastic etc. types) to save the report to or a connection string. It depends on the report type.
type: str
default: none
–deployment <deployment> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Report all tasks with defined deployment
type: str
rally task import¶
Import json results of a test into rally database
Command arguments:
–file <path> [ref]
JSON file with task results
type: str
default: none
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of a deployment.
type: str
–tag <tag> [ref]
Mark the task with a tag or a few tags.
type: str
default: none
rally task list¶
List tasks, started and finished.
Displayed tasks can be filtered by status or deployment. By default ‘rally task list’ will display tasks from the active deployment without filtering by status.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of a deployment.
type: str
–all-deployments [ref]
List tasks from all deployments.
–status <status> [ref]
List tasks with specified status. Available statuses: aborted, aborting, crashed, finished, init, paused, running, sla_failed, soft_aborting, validated, validating, validation_failed
type: str
default: none
–tag <tag> [ref]
Tags to filter tasks by.
type: str
default: none
–uuids-only [ref]
List task UUIDs only.
rally task report¶
Generate a report for the specified task(s).
Command arguments:
–out <path> [ref]
Report destination. Can be a path to a file (in case of HTML, HTML-STATIC, etc. types) to save the report to or a connection string.
type: str
default: none
–open [ref]
Open the output in a browser.
–html [ref]
–html-static [ref]
–json [ref]
–uuid <uuid> [ref]
UUIDs of tasks or json reports of tasks
type: str
default: none
–deployment <deployment> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Report all tasks with defined deployment
type: str
rally task restart¶
Restart a task or some scenarios in workloads of task.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of a deployment.
type: str
–uuid <uuid> [ref]
UUID of task.
type: str
–scenario <scenario> [ref]
Scenario name of workload
type: str
default: none
–tag <tag> [ref]
Mark the task with a tag or a few tags.
type: str
default: none
–no-use [ref]
Don’t set new task as default for future operations.
–abort-on-sla-failure [ref]
Abort the execution of a task when any SLA check for it fails for subtask or workload.
rally task results¶
DEPRECATED since Rally 3.0.0.
Command arguments:
–uuid <uuid> [ref]
UUID of task.
type: str
rally task sla-check¶
Display SLA check results table.
Command arguments:
–uuid <uuid> [ref]
UUID of task.
type: str
–json [ref]
Output in JSON format.
rally task start¶
Run task.
If both task_args and task_args_file are specified, they are going to be merged. task_args has a higher priority so it overrides values from task_args_file. There are 3 kinds of return codes, 0: no error, 1: running error, 2: sla check failed.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of a deployment.
type: str
–task <path>, –filename <path> [ref]
Path to the input task file.
–task-args <json> [ref]
Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.
default: none
–task-args-file <path> [ref]
Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.
default: none
–tag <tag> [ref]
Mark the task with a tag or a few tags.
type: str
default: none
–no-use [ref]
Don’t set new task as default for future operations.
–abort-on-sla-failure [ref]
Abort the execution of a task when any SLA check for it fails for subtask or workload.
rally task status¶
Display the current status of a task.
Command arguments:
–uuid <uuid> [ref]
UUID of task
type: str
rally task trends¶
Generate workloads trends HTML report.
Command arguments:
–out <path> [ref]
Path to output file.
type: str
–open [ref]
Open the output in a browser.
–tasks <tasks> [ref]
UUIDs of tasks, or JSON files with task results
–html-static [ref]
rally task validate¶
Validate a task configuration file.
This will check that task configuration file has valid syntax and all required options of scenarios, contexts, SLA and runners are set.
If both task_args and task_args_file are specified, they will be merged. task_args has a higher priority so it will override values from task_args_file.
Command arguments:
–deployment <uuid> [ref]
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
UUID or name of a deployment.
type: str
–task <path>, –filename <path> [ref]
Path to the input task file.
–task-args <json> [ref]
Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.
default: none
–task-args-file <path> [ref]
Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.
default: none
Category: verify¶
Verify an OpenStack cloud via a verifier.
rally verify add-verifier-ext¶
Add a verifier extension.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–source <source> [ref]
Path or URL to the repo to clone verifier extension from.
type: str
default: none
–version <version> [ref]
Branch, tag or commit ID to checkout before installation of the verifier extension (the ‘master’ branch is used by default).
type: str
default: none
–extra-settings <extra_settings> [ref]
Extra installation settings for verifier extension.
type: str
default: none
rally verify configure-verifier¶
Configure a verifier for a specific deployment.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.
type: str
–reconfigure [ref]
Reconfigure verifier.
–extend <path/json/yaml> [ref]
Extend verifier configuration with extra options. If options are already present, the given ones will override them. Can be a path to a regular config file or just a json/yaml.
type: str
default: none
–override <path> [ref]
Override verifier configuration by another one from a given source.
type: str
default: none
–show [ref]
Show verifier configuration.
rally verify create-verifier¶
Create a verifier.
Command arguments:
–name <name> [ref]
Verifier name (for example, ‘My verifier’).
type: str
–type <type> [ref]
Verifier plugin name. HINT: You can list all verifier plugins, executing command rally verify list-plugins.
type: str
–platform <platform> [ref]
Verifier plugin platform. Should be specified in case of two verifier plugins with equal names but in different platforms.
type: str
default:
–source <source> [ref]
Path or URL to the repo to clone verifier from.
type: str
default: none
–version <version> [ref]
Branch, tag or commit ID to checkout before verifier installation (the ‘master’ branch is used by default).
type: str
default: none
–system-wide [ref]
Use the system-wide environment for verifier instead of a virtual environment.
–extra-settings <extra_settings> [ref]
Extra installation settings for verifier.
type: str
default: none
–no-use [ref]
Not to set the created verifier as the default verifier for future operations.
rally verify delete¶
Delete a verification or a few verifications.
Command arguments:
–uuid <uuid> [ref]
UUIDs of verifications. HINT: You can list all verifications, executing command rally verify list.
type: str
rally verify delete-verifier¶
Delete a verifier.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. If specified, only the deployment-specific data will be deleted for verifier. HINT: You can list all deployments, executing command rally deployment list.
type: str
–force [ref]
Delete all stored verifications of the specified verifier. If a deployment specified, only verifications of this deployment will be deleted. Use this argument carefully! You can delete verifications that may be important to you.
rally verify delete-verifier-ext¶
Delete a verifier extension.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–name <name> [ref]
Verifier extension name.
type: str
default: none
rally verify import¶
Import results of a test run into the Rally database.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.
type: str
–file <path> [ref]
File to import test results from.
type: str
default: none
–run-args <run_args> [ref]
Arguments that might be used when running tests. For example, ‘{concurrency: 2, pattern: set=identity}’.
type: str
default: none
–no-use [ref]
Not to set the created verification as the default verification for future operations.
rally verify list¶
List all verifications.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.
type: str
–tag <tag> [ref]
Tags to filter verifications by.
type: str
default: none
–status <status> [ref]
Status to filter verifications by.
type: str
default: none
rally verify list-plugins¶
List all plugins for verifiers management.
Command arguments:
–platform <platform> [ref]
Requried patform (e.g. openstack).
type: str
default: none
rally verify list-verifier-exts¶
List all verifier extensions.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
rally verify list-verifier-tests¶
List all verifier tests.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–pattern <pattern> [ref]
Pattern which will be used for matching. Can be a regexp or a verifier-specific entity (for example, in case of Tempest you can specify ‘set=smoke’).
type: str
default:
rally verify list-verifiers¶
List all verifiers.
Command arguments:
–status <status> [ref]
Status to filter verifiers by.
type: str
default: none
rally verify report¶
Generate a report for a verification or a few verifications.
Command arguments:
–uuid <uuid> [ref]
UUIDs of verifications. HINT: You can list all verifications, executing command rally verify list.
type: str
default: none
–type <type> [ref]
Report type (Defaults to JSON). Out-of-the-box types: HTML, HTML-Static, JSON, JUnit-XML. HINT: You can list all types, executing rally plugin list –plugin-base VerificationReporter command.
type: str
default: none
–to <dest> [ref]
Report destination. Can be a path to a file (in case of HTML, JSON, etc. types) to save the report to or a connection string. It depends on the report type.
type: str
default: none
–open [ref]
Open the output file in a browser.
rally verify rerun¶
Rerun tests from a verification for a specific deployment.
Command arguments:
–uuid <uuid> [ref]
Verification UUID. HINT: You can list all verifications, executing command rally verify list.
type: str
default: none
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.
type: str
–failed [ref]
Rerun only failed tests.
–tag <tag> [ref]
Mark verification with a tag or a few tags.
type: str
default: none
–concurrency <N> [ref]
How many processes to be used for running verifier tests. The default value (0) auto-detects your CPU count.
type: int
default: none
–detailed [ref]
Show verification details such as errors of failed tests.
–no-use [ref]
Not to set the finished verification as the default verification for future operations.
rally verify show¶
Show detailed information about a verification.
Command arguments:
–uuid <uuid> [ref]
Verification UUID. HINT: You can list all verifications, executing command rally verify list.
type: str
default: none
–sort-by <query> [ref]
Sort tests by ‘name’, ‘duration’ or ‘status’.
type: str
default: name
–detailed [ref]
Show verification details such as run arguments and errors of failed tests.
rally verify show-verifier¶
Show detailed information about a verifier.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
rally verify start¶
Start a verification (run verifier tests).
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–deployment-id <id> [ref]
Note
The default value for the --deployment-id argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.
type: str
–tag <tag> [ref]
Mark verification with a tag or a few tags.
type: str
default: none
–pattern <pattern> [ref]
Pattern which will be used for running tests. Can be a regexp or a verifier-specific entity (for example, in case of Tempest you can specify ‘set=smoke’).
type: str
default: none
–concurrency <N> [ref]
How many processes to be used for running verifier tests. The default value (0) auto-detects your CPU count.
type: int
default: 0
–load-list <path> [ref]
Path to a file with a list of tests to run.
type: str
default: none
–skip-list <path> [ref]
Path to a file with a list of tests to skip. Format: json or yaml like a dictionary where keys are regexes matching test names and values are reasons.
type: str
default: none
–xfail-list <path> [ref]
Path to a file with a list of tests that will be considered as expected failures. Format: json or yaml like a dictionary where keys are test names and values are reasons.
type: str
default: none
–detailed [ref]
Show verification details such as errors of failed tests.
–no-use [ref]
Not to set the finished verification as the default verification for future operations.
rally verify update-verifier¶
Update a verifier.
Command arguments:
–id <id> [ref]
Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.
type: str
default: none
–update-venv [ref]
Update the virtual environment for verifier.
–version <version> [ref]
Branch, tag or commit ID to checkout. HINT: Specify the same version to pull the latest repo code.
type: str
default: none
–system-wide [ref]
Switch to using the system-wide environment.
–no-system-wide [ref]
Switch to using the virtual environment. If the virtual environment doesn’t exist, it will be created.