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

Channel commands:
  get channels                     List known channels

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 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/v1beta1
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
    services:
      receptionist:
        port: 7774
      observer:
        port: 7775
      killswitch:
        port: 7776
      eventbus:
        port: 38368
      agentchannel:
        port: 24368
      qualitygate:
        port: 12312
users:
- name: default
  user:
    token: ey...
    step-depth: ...
    job-depth: ...
    max-command-length: ...

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 server, port, and possibly path prefix, the orchestrator’s services section can be omitted.

If one endpoint is hosted on another server or uses a customized route or port, it can be specified as such:

  ...
  orchestrator:
    server: http://localhost
    services:
      observer:
        prefix: foobar
        port: 1234

That way, instead of performing a workflows’ lookup using http://localhost/workflows, opentf-ctl will use http://localhost:1234/foobar/workflows instead, while still using http://localhost/workflows to run workflows.

Please refer to “config set-orchestrator” for more information.

Proxy and Trusted certificates¶

To override the default certificate bundle used by opentf-ctl, you can set the standard CURL_CA_BUNDLE environment variable.

BashCMDPowerShell

export CURL_CA_BUNDLE="/usr/local/myproxy_info/cacert.pem"
export https_proxy="http://10.10.1.10:1080"
opentf-ctl [...]

set CURL_CA_BUNDLE=/path/to/myproxy_info/cacert.pem
set https_proxy=http://10.10.1.10:1080
opentf-ctl [...]

$Env:CURL_CA_BUNDLE = "/path/to/myproxy_info/cacert.pem"
$Env:https_proxy = "http://10.10.1.10:1080"
opentf-ctl [...]

If the following environment variables are defined in opentf-ctl‘s environment, they will be used:

Environment variable	Format	Description
`http_proxy` or `HTTP_PROXY`	`[protocol://]<host>[:port]`	Sets the proxy server to use for HTTP.
`https_proxy` or `HTTPS_PROXY`	`[protocol://]<host>[:port]`	Sets the proxy server to use for HTTPS.
`no_proxy` or `NO_PROXY`	`<comma-separated list of hosts/domains>`	List of host names that shouldn’t go through any proxy. If set to an asterisk ‘*’ only, it matches all hosts. Each name in this list is matched as either a domain name which contains the hostname, or the hostname itself.
`CURL_CA_BUNDLE`	`<path to file>`	The CA bundle to use.

For the first three environment variables, the lower-cased ones take precedence over the upper-cased ones if both are defined.

The no_proxy or NO_PROXY environment variables, if defined, are interpreted following the Python rules:

It matches suffixes
It strips leading .
* matches all hosts

Regexps are not supported, CIDR blocks are not supported either, and loopback IPs are not detected.

For example, the following two examples will bypass the proxy:

env https_proxy=http://non.existent no_proxy=.example.com opentf-ctl get workflows --server https://example.com
env https_proxy=http://non.existent no_proxy=.example.com opentf-ctl get workflows --server https://orchestrator.example.com

Please refer to “We need to talk: Can we standardize no_proxy?” for more information on how the no_proxy environment variable is interpreted in different contexts.

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

The columns definition format is as follows: 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)
--max_command_length={n}  # show the first n characters of running commands (only used with --wait)
--wait                    # wait until completion or cancellation

Note

You can change the default values of job_depth, step_depth, and max_command_length for a given user using opentf-ctl config set-credentials {user} --job_depth={n}.

What is passed on the command line overrides what is defined for a given user.

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.

BashCMDPowerShell

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 an environment. Those variables can be overridden by using -e parameters.

BashCMDPowerShell

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}           # 1 by default
--step_depth={n}          # 1 by default
--max_command_length={n}  # 15 by default
--watch                   # wait until completion or cancellation

Note

You can change the default values of job_depth, step_depth, and max_command_length for a given user using opentf-ctl config set-credentials {user} --job_depth={n}.

What is passed on the command line overrides what is defined for a given user.

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}           # 1 by default
--step_depth={n}          # 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 command: git clone https...
[2021-10-13T17:18:37] [job 9ea3be45-ee90-4135-b47f-e66e4f793383] Running command: dir
...
Workflow completed successfully.

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

If you want to see the full running command, use --max_command_length=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 follows: 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 in 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 shows 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 depend 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 of 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 follows: 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 follows: 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 (it is not saved to a file).

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

Please refer to “config set-orchestrator” for more configuration options for orchestrators.

`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 options can be passed to this command:

--token: The token to use when acting as this user (a string)
--step_depth: The default value to use for step depth (an integer, 1 by default)
--job_depth: The default value to use for job depth (an integer, 1 by default)
--max_command_length: The default value to use for max command length (an integer, 15 by default)

For step_depth, job_depth, and max_command_length a value of 0 disables the limit.

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

--insecure-skip-tls-verify=false|true: Skip TLS verification
--server=: Address of the opentf orchestrator (string, of the form {protocol}://{domain}[/{context}])
--{SERVICE}-force-base-url=false|true: Override link URLs
--{SERVICE}-port={n}: Port of the service (integer)
--{SERVICE}-prefix={prefix}: Prefix for the service (string)

where SERVICE is one of receptionist, observer, eventbus, killswitch, agentchannel, or qualitygate.

It only sets or changes the specified parameters.

If a SERVICE endpoint is hosted on another server or uses a customized route or port, it can be specified as such:

  orchestrator:
    server: http://localhost
    services:
      observer:
        prefix: foobar
        port: 1234
        force-base-url: true

That way, instead of performing a workflows’ lookup using http://localhost/workflows, opentf-ctl will use http://localhost:1234/foobar/workflows instead, while still using http://localhost/workflows to run workflows.

Information

If force-base-url is set to true for a service, opentf-ctl will ignore the links returned by the service and will always construct the endpoint’s base URL using the server, port, and prefix if defined. It is useful if the orchestrator you are using is behind an incorrectly-configured reverse proxy you have no control of.

`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"}

Running commands¶

Configuration¶

Proxy and Trusted certificates¶

Basic commands¶

get workflows¶

Optional parameters¶

Wide view¶

Custom view¶

run workflow {file_name}¶

Optional parameters¶

Sending variables¶

Sending files¶

Waiting for completion¶

get workflow {workflow_id}¶

Optional parameters¶

Nested jobs and steps¶

Waiting for completion¶

kill workflow {workflow_id}¶

Agent commands¶

get agents¶

Optional parameters¶

Wide view¶

Custom view¶

delete agent {agent_id}¶

Quality gate commands¶

get qualitygate {workflow_id}¶

Optional parameters¶

Tokens commands¶

generate token using {key}¶

check token {token} using {key}¶

view token {token}¶

Advanced commands¶

get channels¶

Optional parameters¶

Wide view¶

Custom view¶

get subscriptions¶

Optional parameters¶

Wide view¶

Custom view¶

Other commands¶

config generate¶

config view¶

config use-context¶

config set-context¶

config delete-context¶

config set-credentials¶

config delete-credentials¶

config set-orchestrator¶

config delete-orchestrator¶

version¶

`get workflows`¶

`run workflow {file_name}`¶

`get workflow {workflow_id}`¶

`kill workflow {workflow_id}`¶

`get agents`¶

`delete agent {agent_id}`¶

`get qualitygate {workflow_id}`¶

`generate token using {key}`¶

`check token {token} using {key}`¶

`view token {token}`¶

`get channels`¶

`get subscriptions`¶

`config generate`¶

`config view`¶

`config use-context`¶

`config set-context`¶

`config delete-context`¶

`config set-credentials`¶

`config delete-credentials`¶

`config set-orchestrator`¶

`config delete-orchestrator`¶

`version`¶