Skip to content

Running commands

Note

opentf-ctl is a component of opentf-tools, which must be installed before use. Please refer to “Install tools” for more information on how to install.

opentf-ctl controls the OpenTestFactory orchestrators.

Basic Commands:
  get workflows                    List active and recent workflows
  run workflow {filename}          Start a workflow
  get workflow {workflow_id}       Get a workflow status
  kill workflow {workflow_id}      Cancel a running workflow

Agent Commands:
  get agents                       List registered agents
  delete agent {agent_id}          De-register an agent

Qualitygate Commands:
  get qualitygate {workflow_id}    Get qualitygate status for a workflow

Token Commands:
  generate token using {key}       Interactively generate a signed token
  check token {token} using {key}  Check if token signature matches public key
  view token {token}               Show token payload

Advanced Commands:
  get channels                     List active execution environments
  get subscriptions                List active subscriptions

Other Commands:
  config                           Modify current opentf-tools configuration
  version                          List the tools version

Usage:
  opentf-ctl <command> [options]

Use "opentf-ctl <command> --help" for more information about a given command.
Use "opentf-ctl options" for a list of global command-line options (applies to all commands).

Configuration

opentf-ctl requires a configuration file. By default this configuration file is expected to be ~/.opentf/config. This location can be overridden by defining the OPENTF_CONFIG environment variable or by using the --opentfconfig command-line option.

If the command-line option is specified, then it is used as the configuration file. Otherwise, if the environment variable is set, it is used as the configuration file location. Otherwise the configuration file location is expected to be ~/.opentf/config.

The configuration file is a YAML file with the following structure:

apiVersion: opentestfactory.org/v1alpha1
kind: CtlConfig
current-context: default
contexts:
- context:
    orchestrator: default
    user: default
  name: default
orchestrators:
- name: default
  orchestrator:
    insecure-skip-tls-verify: true
    server: http://localhost
    ports:
      receptionist: 7774
      observer: 7775
      killswitch: 7776
      eventbus: 38368
      agentserver: 24368
      qualitygate: 12312
users:
- name: default
  user:
    token: ey...

It contains a series of contexts that specify an orchestrator and a user. By default, the used context will be the one specified by current-context, but this can be overridden by using the --context command-line option.

The orchestrator specified by the selected context can be overridden by using the --orchestrator command-line option.

The user specified by the selected context can be overridden by using the --user command-line option.

The orchestrator’s tls-verify status can be overridden by using the --insecure-skip-tls-verify command-line option.

The user’s token can be overridden by defining the OPENTF_TOKEN environment variable or the --token command-line option.

If the command-line option is specified, then it is used as the token. Otherwise, if the environment variable is set, it is used as the token. Otherwise, the token value set for the user in the configuration file is used as the token.

If the orchestrator endpoints all listen on the same port, the orchestrator’s port section can be omitted.

Basic commands

get workflows

This command lists active and recent workflows.

opentf-ctl get workflows
WORKFLOWID,STATUS,NAME
6c223f7b-3f79-4c51-b200-68eaa33c1325,DONE,RobotFramework Example
31b5e665-819c-4e92-862a-f05d1993c096,DONE,RobotFramework Example

It returns workflow IDs, which are unique identifiers that can be used by the get workflow {workflow_id} command.

Optional parameters

The get workflows command allows for one additional optional parameter:

--output=wide or -o wide                        # show additional information
--output=custom-columns= or -o custom-columns=  # show specified information

If you specify both wide and custom-columns, the custom columns specification wins.

Wide view

If this optional parameter is specified, the execution status, the first time the workflow was seen, and the workflow name are displayed.

opentf-ctl get workflows --output=wide
WORKFLOW_ID,STATUS,FIRST_SEEN_TIMESTAMP,WORKFLOW_NAME
68e81c2b-1520-42bd-a5f3-b30458f6948a,DONE,2021-12-14T14:51:18.280384,RobotFramework Example
7e0dbbec-fa69-45ec-8707-754d994a0cc3,DONE,2021-12-14T14:51:19.635299,RobotFramework Example
3766701b-c250-4eeb-92be-e4718a9c24ad,DONE,2021-12-14T14:51:21.419208,RobotFramework Example
1ee5f091-f234-40cd-b853-9d46fe46ceb6,DONE,2021-12-14T14:51:23.614088,RobotFramework Example
Custom view

If this optional parameter is specified, you can choose what is displayed for each active and recent workflows.

The columns definition format is as follow: name:value[,name:value]*. name is the column name in the output (WORKFLOW_ID or WORKFLOW_NAME in the example above). value is the path to the information in the workflow schema.

The following values are supported:

  • .metadata.workflow_id
  • .metadata.name
  • .metadata.creationTimestamp
  • .details.status
opentf-ctl get workflows --output=custom-columns=ID:.metadata.workflow_id,NAME:.metadata.name
WORKFLOW_ID,NAME
68e81c2b-1520-42bd-a5f3-b30458f6948a,RobotFramework Example
7e0dbbec-fa69-45ec-8707-754d994a0cc3,RobotFramework Example
3766701b-c250-4eeb-92be-e4718a9c24ad,RobotFramework Example
1ee5f091-f234-40cd-b853-9d46fe46ceb6,RobotFramework Example

run workflow {file_name}

This command starts a workflow. It requires one parameter, an existing file name.

opentf-ctl run workflow demo_windows_robotframework.yaml
Workflow 7aa1e1a4-4ede-4ab9-aa80-f9213d057397 is running.

It returns a workflow ID, which is a unique identifier for the started workflow.

Optional parameters

The run workflow command allows for additional optional parameters, in no specific order, but they must follow the command if used:

-e var=value       # define variable
-e path            # define variables
-f name=path       # send file with workflow
--step_depth=n     # show nested steps to a given depth (only used with --wait)
--job_depth=n      # show nested jobs to a given depth (only used with --wait)
--wait             # wait until completion or cancellation
Sending variables

You can provide variables for your workflow execution by using the -e variable=value command-line option, repeatedly if needed.

If you have a set of variables you want to provide for your workflow execution, you can use the -e path command-line option, repeatedly if needed.

opentf-ctl \
  run workflow demo_windows_robotframework.yaml \
  -e .env \
  -e PASSWORD=$PASSWORD
opentf-ctl ^
  run workflow demo_windows_robotframework.yaml ^
  -e .env ^
  -e PASSWORD=%PASSWORD%
opentf-ctl `
  run workflow demo_windows_robotframework.yaml `
  -e .env `
  -e PASSWORD=$Env:PASSWORD

The options are processed in order, and the last value of a given variable is what will be available during the workflow execution.

Environment variables with an OPENTF_RUN_ prefix will be defined without the prefix in the workflow and while running commands in execution environment. Those variables can be overridden by using -e parameters.

export OPENTF_RUN_FOO=foo
export OPENTF_RUN_BAR=bar
opentf-ctl run workflow demo.yaml -e FOO=foobar
set OPENTF_RUN_FOO=foo
set OPENTF_RUN_BAR=bar
opentf-ctl run workflow demo.yaml -e FOO=foobar
$Env:OPENTF_RUN_FOO = "foo"
$Env:OPENTF_RUN_BAR = "bar"
opentf-ctl run workflow demo.yaml -e FOO=foobar

In the workflow, FOO will be foobar and BAR will be bar.

Sending files

If your workflow requires it, you can join files by using the -f name=file command-line option, repeatedly if needed.

opentf-ctl run workflow demo_windows_robotframework.yaml -f report=data/report.html -f key=secret/key.pem
Workflow 03680dca-6b6a-4eac-a082-ffd164e8f8e0 is running.
Waiting for completion

By default, the run workflow command starts a workflow and immediately returns.

If you use the --wait command-line option, it will wait until the workflow completion or cancellation.

Stopping or interrupting the command does not cancel the running workflow.

opentf-ctl run workflow demo_windows_robotframework.yaml --wait
Workflow 7aa1e1a4-4ede-4ab9-aa80-f9213d057397 is running.
...
Workflow completed successfully.

get workflow {workflow_id}

This command shows the running status of the specified workflow.

opentf-ctl get workflow 396e99ec-0fe4-4f35-8b9e-69a550a0e474
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Requesting execution environment providing ['windows', 'robotframework'] for job keyword-driven
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running actionscheckoutv2
[2021-10-13T17:18:37] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running ['dir']
[2021-10-13T17:18:42] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running robotframeworkrobotv1
Workflow completed successfully.

The last line can take four values:

  • Workflow completed successfully.
  • Workflow is running.
  • Workflow cancelled.
  • Workflow failed.

Optional parameters

The get workflow command allows for additional optional parameters, in no specific order, but they must follow the command if used:

--job_depth=<n>     # --job_depth=1 by default
--step_depth=<n>    # --step_depth=1 by default
--watch             # wait until completion or cancellation
Nested jobs and steps

By default, the nested steps and jobs are hidden. If you want to see the jobs produced by generators or the steps produces by generators, you can add the following parameters:

--job_depth=<n>     # --job_depth=1 by default
--step_depth=<n>    # --step_depth=1 by default
opentf-ctl get workflow 396e99ec-0fe4-4f35-8b9e-69a550a0e474 --step_depth=2
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Requesting execution environment providing ['windows', 'robotframework'] for job keyword-driven
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running actionscheckoutv2
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383]  Running ['git clone https://github.com/robotframework/RobotDemo.git']
[2021-10-13T17:18:37] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running ['dir']
...
Workflow completed successfully.

If you want to view all jobs and all steps, use --job_depth=0 and --step_depth=0.

Waiting for completion

By default, the get workflow command shows the running status of a workflow and immediately returns.

If you use the --watch command-line option, it will wait until the workflow completion or cancellation.

Stopping or interrupting the command does not cancel the running workflow.

opentf-ctl get workflow 396e99ec-0fe4-4f35-8b9e-69a550a0e474 --watch
[2021-10-13T17:18:33] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Requesting execution environment providing ['windows', 'robotframework'] for job keyword-driven
...
Workflow completed successfully.

kill workflow {workflow_id}

This command kills a running workflow.

opentf-ctl kill workflow aa6e99ec-0fe4-4f35-8b9e-69a550a0e4ed
Killing workflow aa6e99ec-0fe4-4f35-8b9e-69a550a0e4ed.

Agent commands

get agents

This command lists registered agents.

opentf-ctl get agents
NAME,AGENT_ID,TAGS,REGISTRATION_TIMESTAMP,LAST_SEEN_TIMESTAMP,RUNNING_JOB
test agent,c07d0ac5-5943-4769-8e8d-2ee809e75ee8,windows:robotframework,2021-12-03T18:13:13.71,2021-12-03T18:13:23.80,6a22d890-6210-479a-aa91-b4497113512e

It returns agent IDs, which are unique identifiers that can be used by the delete agent {agent_id} command.

The last column, RUNNING_JOB, is empty if the agent is currently idle. It contains the job ID it is currently processing otherwise.

Optional parameters

The get agents command allows for one additional optional parameter:

--output=wide or -o wide                        # show additional information
--output=custom-columns= or -o custom-columns=  # show specified information

If you specify both wide and custom-columns, the custom columns specification wins.

Wide view

This option shows the default columns, as above.

opentf-ctl get agents -o wide
NAME,AGENT_ID,TAGS,REGISTRATION_TIMESTAMP,LAST_SEEN_TIMESTAMP,RUNNING_JOB
test agent,c07d0ac5-5943-4769-8e8d-2ee809e75ee8,windows:robotframework,2021-12-03T18:13:13.71,2021-12-03T18:13:23.80,6a22d890-6210-479a-aa91-b4497113512e
Custom view

If this optional parameter is specified, you can choose what is displayed for each registered agent.

The columns definition format is as follow: name:value[,name:value]*. name is the column name in the output (AGENT_ID or NAME in the example above). value is the path to the information in the agent registration schema.

The following values are supported:

  • .metadata.agent_id
  • .metadata.name
  • .metadata.namespaces
  • .metadata.creationTimestamp
  • .spec.tags
  • .status.lastCommunicationTimestamp
  • .status.currentJobID
opentf-ctl get agents --output=custom-columns=ID:.metadata.agent,NAME:.metadata.name
ID,NAME
c07d0ac5-5943-4769-8e8d-2ee809e75ee8,test agent

delete agent {agent_id}

This command de-registers agents.

opentf-ctl delete agent 6c223f7b-3f79-4c51-b200-68eaa33c1325

If the agent is currently processing a job, the corresponding workflow may fail and the workspace on the execution environment may remain.

Quality gate commands

get qualitygate {workflow_id}

This command queries the quality gate status for the specified workflow.

There are two predefined quality gates: strict and passing. The strict quality gate is the default. You can use another quality gate by using the --mode= command line option.

The strict quality gate passes if all tests were successful during the workflow execution. The passing quality gate always passes.

The get qualitygate return code is:

  • 0 if the quality gate passed for the specified workflow
  • 101 if the specified workflow is still running
  • 102 if the quality gate failed for the specified workflow

Other return codes indicate a non-functional problem with the command (unknown workflow, unknown quality gate, …).

A workflow that contains no test will always pass the quality gate.

Optional parameters

The get qualitygate command allows for additional optional parameters, in no specific order, but they must follow the command if used:

--mode=<mode>   # mode is `strict` or `passing`

If --mode is not specified, strict is assumed.

Tokens commands

generate token using {key}

This command generates a signed token.

The specified key must be a valid private key. If you do not already have one, you can create it using the following commands:

openssl genrsa -out trusted_key.pem 4096
openssl rsa -pubout -in trusted_key.pem -out trusted_key.pub

You can then use the command to create as many tokens as needed:

opentf-ctl generate token using trusted_key.pem
Please specify an algorithm (RS512 if unspecified):
The specified algorithm is: RS512
Please enter the issuer (your company or department): acme
Please enter the subject (you or the person you are making this token for): charlie
The signed token is:
ey...

check token {token} using {key}

This command checks if the token signature matches the specified public key.

opentf-ctl check token ey... using trusted_key.pub

If the token signature matches the payload is displayed:

The token is signed by the trusted_key.pub public key.  The token payload is:
{'iss': 'acme', 'sub': 'foo'}

If the token signature does not match, an error message is displayed:

ERROR:root:The token is not signed by trusted_key_2.pub.

view token {token}

This command show the token payload.

opentf-ctl view token ey...
The token payload is:
{'iss': 'acme', 'sub': 'foo'}

This command does not check the token signature. It will work even if the signature is missing or corrupted.

If the token is invalid, an error message is displayed. The error message will depends on the cause of invalidity.

ERROR:root:Could not validate token signature: Invalid payload padding.

Advanced commands

get channels

This command lists known execution environments.

opentf-ctl get channels
NAME,NAMESPACES,TAGS,LAST_REFRESH_TIMESTAMP,STATUS
robotframework.agents,default,ssh:linux:robotframework,2022-05-02T10:14:50.39,IDLE
cypress-agent.agents,default,ssh:linux:cypress,2022-05-02T10:14:50.39,IDLE
cucumber.agents,*,ssh:linux:cucumber,2022-05-02T10:14:50.39,IDLE
junit.agents,foo:bar,ssh:linux:junit,2022-05-02T10:14:50.39,IDLE

The first item is the execution environment name, the second item is the namespace(s) this execution environment is accessible from (if it is *, it is available for all namespaces), the third item is a list tags separated by :, the fourth item is when the environment details were refreshed for the last time, and the last item is the execution environment status (IDLE, PENDING, or BUSY).

An IDLE execution environment is currently not doing any orchestrator-related tasks. A PENDING execution environment has been offered to handle a job, but has not been selected (yet). A BUSY execution environment is currently handling a job.

Optional parameters

The get channels command allows for one additional optional parameter:

--output=wide or -o wide                        # show additional information
--output=custom-columns= or -o custom-columns=  # show specified information

If you specify both wide and custom-columns, the custom columns specification wins.

Wide view

This option shows the default columns, as well as the channel handler ID.

opentf-ctl get subscriptions -o wide
HANDLER_ID,NAME,NAMESPACE,TAGS,LAST_SEEN_TIMESTAMP,STATUS
f82bede2-d66b-49b2-9176-a82b29d8bded,robotframework.agents,default,ssh:linux:robotframework,2022-05-02T15:57:47.60,IDLE
f82bede2-d66b-49b2-9176-a82b29d8bded,cypress-agent.agents,default,ssh:linux:cypress,2022-05-02T15:57:47.60,IDLE
f82bede2-d66b-49b2-9176-a82b29d8bded,cucumber.agents,*,ssh:linux:cucumber,2022-05-02T15:57:47.60,IDLE
f82bede2-d66b-49b2-9176-a82b29d8bded,junit.agents,foo:bar,ssh:linux:junit,2022-05-02T15:57:47.60,IDLE
Custom view

If this optional parameter is specified, you can choose what is displayed for each known execution environment.

The columns definition format is as follow: name:value[,name:value]*. name is the column name in the output (such as NAME in the example above). value is the path to the information in the service subscription schema.

The following values are supported:

  • .metadata.name
  • .metadata.namespaces
  • .metadata.channelhandler_id
  • .spec.tags
  • .status.lastCommunicationTimestamp
  • .status.phase
  • .status.currentJobID
opentf-ctl get channels --output=custom-columns=NAME:.metadata.name
NAME
robotframework.agents
cypress-agent.agents
cucumber.agents
junit.agents

get subscriptions

This command lists active subscriptions on the eventbus.

opentf-ctl get subscriptions
NAME,ENDPOINT,CREATION,COUNT,SUBSCRIPTION
actionprovider,http://127.0.0.1:9065/inbox,2021-12-14T14:50:57.12,20,"kind==ProviderCommand:opentestfactory.org/category==delete-file,opentestfactory.org/categoryPrefix==actions"
junit,http://127.0.0.1:9865/inbox,2021-12-14T14:50:57.79,0,"kind==ProviderCommand:opentestfactory.org/category==mvntest,opentestfactory.org/categoryPrefix==junit,opentestfactory.org/categoryVersion==v1"
actionprovider,http://127.0.0.1:9065/inbox,2021-12-14T14:50:57.44,0,"kind==ProviderCommand:opentestfactory.org/category==put-file,opentestfactory.org/categoryPrefix==actions"
localcleaner,http://127.0.0.1:9566/inbox,2021-12-14T14:50:55.86,0,kind==WorkflowCanceled:
observer,http://127.0.0.1:9565/inbox,2021-12-14T14:50:55.21,4,"kind==Workflow,apiVersion==opentestfactory.org/v1alpha1:"
observer,http://127.0.0.1:9565/inbox,2021-12-14T14:50:56.46,0,"kind==GeneratorCommand,apiVersion==opentestfactory.org/v1alpha1:"
robotframework,http://127.0.0.1:9265/inbox,2021-12-14T14:50:57.46,0,"kind==ProviderCommand,apiVersion==opentestfactory.org/v1alpha1:opentestfactory.org/category==params,opentestfactory.org/categoryPrefix==robotframework,opentestfactory.org/categoryVersion==v1"
actionprovider,http://127.0.0.1:9065/inbox,2021-12-14T14:50:57.60,0,"kind==ProviderCommand:opentestfactory.org/category==touch-file,opentestfactory.org/categoryPrefix==actions"
robotframework,http://127.0.0.1:9265/inbox,2021-12-14T14:50:57.05,4,"kind==ProviderCommand,apiVersion==opentestfactory.org/v1alpha1:opentestfactory.org/category==robot,opentestfactory.org/categoryPrefix==robotframework,opentestfactory.org/categoryVersion==v1"
junit,http://127.0.0.1:9865/inbox,2021-12-14T14:50:57.89,0,"kind==ProviderCommand:opentestfactory.org/category==params,opentestfactory.org/categoryPrefix==junit,opentestfactory.org/categoryVersion==v1"

The first item is the service name, the second item is the service endpoint, the third item is the subscription date, the fourth item is the number of events sent for this subscription, and the last item is the subscription detail (the kind of events that match the subscription).

Optional parameters

The get subscriptions command allows for one additional optional parameter:

--output=wide or -o wide                        # show additional information
--output=custom-columns= or -o custom-columns=  # show specified information

If you specify both wide and custom-columns, the custom columns specification wins.

Wide view

This option shows the default columns, as above.

opentf-ctl get subscriptions -o wide
NAME,ENDPOINT,CREATION,COUNT,SUBSCRIPTION
actionprovider,http://127.0.0.1:9065/inbox,2021-12-14T14:50:57.12,20,"kind==ProviderCommand:opentestfactory.org/category==delete-file,opentestfactory.org/categoryPrefix==actions"
Custom view

If this optional parameter is specified, you can choose what is displayed for each registered agent.

The columns definition format is as follow: name:value[,name:value]*. name is the column name in the output (such as NAME in the example above). value is the path to the information in the service subscription schema.

The following values are supported:

  • .metadata.name
  • .metadata.creationTimestamp
  • .metadata.annotations
  • .spec.subscriber.endpoint
  • .status.publicationCount
opentf-ctl get subscriptions --output=custom-columns=NAME:.metadata.name
NAME
junit

Other commands

config generate

This command generates a config file from user input. The generated configuration file is printed in the stdout stream.

opentf-ctl config generate

The following options can be passed to this command:

  • --name: Nickname that will be used for context and orchestrator registration (default:default)
  • --orchestrator-server: Address of the opentf orchestrator
  • --orchestrator-receptionist-port: Port of the receptionist service (integer) (default:7774)
  • --orchestrator-observer-port: Port of the observer service (integer) (default:7775)
  • --orchestrator-eventbus-port: Port of the eventbus service (integer) (defaut:38368)
  • --orchestrator-agentchannel-port: Port of the agent channel service (integer) (defaut:24368)
  • --orchestrator-killswitch-port: Port of the killswitch service (integer) (default:7776)
  • --orchestrator-qualitygate-port: Port of the qualitygate service (integer) (default:12312)
  • --insecure-skip-tls-verify=false|true: Skip TLS verification (default:false)
  • --token: User’s token to sign communications with orchestrator

config view

This command displays in the console the current configuration file

opentf-ctl config view

The displayed configuration will be in order of priority the one pointed by

  • the --opentfconfig argument value
  • the environment variable OPENTF_CONFIG
  • the current user configuration located at ~/.opentf/config

config use-context

This command sets the current context.

opentf-ctl config use-context foo

The context must exist.

config set-context

This command creates or updates a context entry.

opentf-ctl config set-context my_context --user=admin --orchestrator=e2e
The following options can be passed to this command:

  • --orchestrator: Name of an existing orchestrator entry
  • --user: Name of an existing user
  • --namespace: The namespace to use when starting workflows with no explicit namespace defined

You can use --current as the context name, in which case the current context will be updated.

config delete-context

This command deletes an existing context.

opentf-ctl config delete-context my_context

config set-credentials

This command creates or updates a user entry.

opentf-ctl config set-credentials my_user --token=ey...

The following option can be passed to this command:

  • --token: The token to use when acting as this user

config delete-credentials

This command deletes an existing user.

opentf-ctl config delete-credentials my_user

If contexts are referring to this user, they remain unchanged.

config set-orchestrator

This command creates or updates an orchestrator entry.

opentf-ctl config set-orchestrator my_orchestrator --server=https://1.2.3.4

The following options can be passed to this command:

  • agentchannel-port: Port of the agentchannel service (integer)
  • eventbus-port: Port of the eventbus service (integer)
  • insecure-skip-tls-verify=false|true: Skip TLS verification
  • killswitch-port: Port of the killswitch service (integer)
  • observer-port: Port of the observer service (integer)
  • receptionist-port: Port of the receptionist service (integer)
  • qualitygate-port: Port of the qualitygate service (integer)
  • server: Address of the orchestrator

It only sets or changes the specified parameters.

config delete-orchestrator

This command deletes an existing orchestrator.

opentf-ctl config delete-orchestrator my_orchestrator

If contexts are referring to this orchestrator, they remain unchanged.

version

This command displays the tools version.

opentf-ctl version
Tools Version: version.Info{Major:"0", Minor: "29", FullVersion: "0.29.2"}