Command Line Interface

Category: db

Commands for DB management.

rally-manage db create

Create Rally database.

rally-manage db recreate

Drop and create Rally database.

This will delete all existing data.

rally-manage db revision

Print current Rally database revision UUID.

rally-manage db upgrade

Upgrade Rally database to the latest state.

Category: deployment

Set of commands that allow you to manage deployments.

rally deployment check

Check keystone authentication 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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

If you use the ExistingCloud deployment engine you can pass a 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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

UUID or name of the deployment.

Type: str

rally deployment use

Set active deployment.

Command arguments:

--deployment <uuid> (ref)

UUID or name of a deployment.

Type: str

Category: plugin

Set of commands that allow you to manage Rally plugins.

rally plugin list

List all Rally plugins that match name and namespace.

Command arguments:

--name <name> (ref)

List only plugins that match the given name.

Type: str

Default: None

--namespace <namespace> (ref)

List only plugins that are in the specified namespace.

Type: str

Default: None

--plugin-base <plugin_base> (ref)

Plugin base class.

Type: str

Default: None

rally plugin show

Show detailed information about a Rally plugin.

Command arguments:

--name <name> (ref)

Plugin name.

Type: str

--namespace <namespace> (ref)

Plugin namespace.

Type: str

Default: None

Category: task

Set of commands that allow you to manage benchmarking tasks and results.

rally task abort

Abort a running benchmarking 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

Print detailed information about given task.

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.

rally task export

Export task results to the custom task's exporting system.

Command arguments:

--uuid <uuid> (ref)

UUID of a the task.

Type: str

--connection <connection> (ref)

Connection url to the task export system.

Type: str

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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, cleaning up, failed, finished, init, paused, running, setting up, soft_aborting, verifying

Type: str

Default: None

--uuids-only (ref)

List task UUIDs only.

rally task report

Generate report file for specified task.

Command arguments:

--tasks <tasks> (ref)

UUIDs of tasks, or JSON files with task results

Default: None

--out <path> (ref)

Path to output file.

Type: str

Default: None

--open (ref)

Open the output in a browser.

--html (ref)

Generate the report in HTML.

--html-static (ref)

Generate the report in HTML with embedded JS and CSS, so it will not depend on Internet availability.

--junit (ref)

Generate the report in the JUnit format.

rally task results

Display raw task results.

This will produce a lot of output data about every iteration.

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 sla_check

DEPRECATED since Rally 0.8.0, use rally task sla-check instead.

Command arguments:

--uuid <uuid> (ref)

UUID of task.

Type: str

--json (ref)

Output in JSON format.

rally task start

Start benchmark task.

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

UUID or name of a deployment.

Type: str

--task <path>, --filename <path> (ref)

Note

The default value for the --task argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally task start, if the --no-use argument was not used.

Hint

You can set the default value by executing rally task use <uuid> (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)

Tag for this task

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 benchmark scenario whenany SLA check for it fails.

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

rally task use

Set active task.

Command arguments:

--uuid <uuid> (ref)

UUID of the task

Type: str

--task (ref)

[Deprecated since Rally 0.2.0] Use '--uuid' instead.

Type: str

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

UUID or name of a deployment.

Type: str

--task <path>, --filename <path> (ref)

Note

The default value for the --task argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally task start, if the --no-use argument was not used.

Hint

You can set the default value by executing rally task use <uuid> (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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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

--namespace <name> (ref)

Verifier plugin namespace. Should be specified in case of two verifier plugins with equal names but in different namespaces.

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: master

--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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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:

--namespace <name> (ref)

Namespace name (for example, 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 types) to save the report to or a connection string. It depends on 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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

Deployment name or UUID. HINT: You can list all deployments, executing command rally deployment list.

Type: str

--failed (ref)

Rerun only failed tests.

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.

Hint

You can set the default value by executing rally deployment use <uuid> (ref).

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 use to run 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 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.

rally verify use

Choose a verification to use for the future operations.

Command arguments:

--uuid <uuid> (ref)

Verification UUID. HINT: You can list all verifications, executing command rally verify list.

Type: str

rally verify use-verifier

Choose a verifier to use for the future operations.

Command arguments:

--id <id> (ref)

Verifier name or UUID. HINT: You can list all verifiers, executing command rally verify list-verifiers.

Type: str