Skip to content

Agent commands

The opentf-ctl tool provides a set of commands to manage agents. You can list and deregister agents.

For more information on agents, see “Agents.”

get agents

This command lists registered agents.

opentf-ctl get agents

AGENT_ID                              NAME        NAMESPACES  TAGS                           REGISTRATION_TIMESTAMP      LAST_SEEN_TIMESTAMP         RUNNING_JOB
53fb7037-d91a-4df1-9181-dacfee6d273f  test agent  default     ["windows", "robotframework"]  2023-09-08T14:42:45.557246  2023-09-08T15:18:57.617358  <none>
a285a1dc-7813-4237-bc93-1b90c17c6274  test agent  default     ["linux", "robotframework"]    2023-09-08T15:18:40.421573  2023-09-08T15:19:00.456028  <none>

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

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

Optional parameters

The get agents command allows for additional optional parameters:

--output=wide or -o wide                        # show additional information
--output=custom-columns= or -o custom-columns=  # show specified information
--output=json or -o json                        # show information in JSON format
--output=yaml or -o yaml                        # show information in YAML format
--selector={s} or -l {s}                        # filter the output on label selector(s)
--field-selector={s}                            # filter the output on field selector(s)

You can only specify one output format at a time. Please refer to “Output formats” for more information.

For more information on selectors, see “selectors.”

Wide view

This option shows the default columns, as above.

opentf-ctl get agents -o wide
opentf-ctl get agents --output=wide

AGENT_ID                              NAME        NAMESPACES  TAGS                           REGISTRATION_TIMESTAMP      LAST_SEEN_TIMESTAMP         RUNNING_JOB
53fb7037-d91a-4df1-9181-dacfee6d273f  test agent  default     ["windows", "robotframework"]  2023-09-08T14:42:45.557246  2023-09-08T15:18:57.617358  <none>
a285a1dc-7813-4237-bc93-1b90c17c6274  test agent  default     ["linux", "robotframework"]    2023-09-08T15:18:40.421573  2023-09-08T15:19:00.456028  <none>

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 -o custom-columns=ID:.metadata.agent_id,NAME:.metadata.name
opentf-ctl get agents --output=custom-columns=ID:.metadata.agent_id,NAME:.metadata.name

ID                                    NAME
53fb7037-d91a-4df1-9181-dacfee6d273f  test agent
a285a1dc-7813-4237-bc93-1b90c17c6274  test agent

Using selectors

By default the get agents command lists all registered agents.

The command output may be restricted by using the --selector and --field-selector options. For example, you may restrict command output to show only agents providing the windows tag:

opentf-ctl get agents --field-selector="(windows) in spec.tags"

AGENT_ID                              NAME        NAMESPACES  TAGS                           REGISTRATION_TIMESTAMP      LAST_SEEN_TIMESTAMP         RUNNING_JOB
53fb7037-d91a-4df1-9181-dacfee6d273f  test agent  default     ["windows", "robotframework"]  2023-09-08T14:42:45.557246  2023-09-08T15:21:53.044245  <none>

You can combine selectors with output format.

For more information on selectors, see “selectors.”

delete agent {agent_id}

This command de-registers agents.

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

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

You can specify partial agent IDs, as long as they are unique (if they are not, a message is displayed and the ambiguous agents are not de-registered).

Optional parameters

The delete agent command allows for additional optional parameters:

--all                               # de-register all running agents
--selector={s} or -l {s}            # de-register agents based on label selector(s)
--field-selector={s}                # de-register agents based on field selector(s)

You cannot mix --all with --selector or --field-selector, and you cannot use those options when specifying agent IDs.

For more information on selectors, see “selectors.”