OET Command Line Interface

This pages covers configuring and general use of the OET CLI. For a step by step guide on how to run a basic test script see How-to: run demo scripts with CLI.

The OET CLI offers login functionality that works with the OET AAA. See Authentication, Authorisation and Auditing.

The OET is a server side application that will be deployed to a Kubernetes environment as described in the previous section. There is an OET CLI which acts as a client for a given deployment of the OET which is defined in a separate ska-oso-oet-client repository. This OET user guide covers using this CLI, as users will primarily interact with the OET from a terminal using the CLI client.

Once the CLI is installed, the oet command can be used to control a remote OET deployment using two sub-commands, procedure and activity.

oet procedure commands are used to control individual observing scripts, which includes loading and starting and stopping script execution.

oet activity commands are used to execute more general activities on the telescope, for example running the observe activity on SB with ID xxx.

See Procedure and Activity sections for further details on commands available for each of the approaches.

General help and specific help is available at the command line by adding the --help argument. For example:

# get a general overview of the OET CLI
$ oet procedure --help
$ oet activity --help

# get specific help on the oet create command
$ oet procedure create --help

# get specific help on the oet describe command
$ oet activity describe --help

Control of multiple subarrays

As explained in Deployment to Kubernetes, the OET controls multiple subarrays by deploying an instance per subarray. The OET CLI can then be used to control multiple OET instances from the same terminal.

It does this via a --subarray_id=<ID> parameter that all oet commands accept. This is then used to construct the correct Ingress URL for the subarray (which is why the OET_URL that is set up at the start of the session has a {SUBARRAY_ID} placeholder - see below).

Alternatively, if the same subarray is being used for the full terminal session, the {SUBARRAY_ID} placeholder in the OET_URL environment variable can be set to the actual value to be used by all the commands.

Installation

The OET command line tool is available as the oet command at the terminal. The OET CLI is packaged separately so it can be installed without OET backend dependencies, such as PyTango. It can be installed into a Python environment, and configured to access a remote OET deployment as detailed below:

$ pip install --upgrade ska_oso_oet_client -i https://artefact.skao.int/repository/pypi-all/simple

By default, the OET image has the CLI installed, meaning the CLI is accessible from inside the running OET pod. If you have direct access to an OET pod, you can execute OET commands which will connect with the OET server running inside the same pod.

Configuration

The OET CLI is a client that can be configured to connect with any deployed instance of the OET via the URL of the instance’s RESTful API.

Note

The URL for a given deployment of the OET should be deducible following the OSO pattern. Generally, it will be <HOST>/<KUBE_NAMESPACE>/oet/<SUBARRAY_ID>/api/v<OET MAJOR VERSION>.

The URL can be configured through a server-url CLI argument, or set session-wide by setting the OET_URL environment variable. This should be used to configure the CLI to access an OET deployment via an Ingress address, a Kubernetes Service or a LoadBalancer, e.g.

$ export OET_URL=https://k8s.stfc.skao.int/ska-oso-integration/oet/{SUBARRAY_ID}/api/v<MAJOR_VERSION>

The {SUBARRAY_ID} is a placeholder and should be left in this format - it is overwritten per command as described above.

Alternatively the URL can be passed into a command:

# provide the server URL when running the command, e.g.
$ oet --server-url=<KUBE_HOST>/<KUBE_NAMESPACE>/oet/<SUBARRAY_ID>/api/v<OET MAJOR VERSION> procedure list

Authentication

In order to communicate with the OET back-end service, the OET CLI requires user authentication. To log in, use the login command. This will open a browser with a login prompt. If the browser does not open automatically, the CLI logs contain a link to the login page.

A successful login stores the personal access token locally and the OET CLI commands can be used without further authentication until the token has expired.

Commands

Common

The oet CLI tool has listen command which is neither activity or procedure specific. It is used to observe OET messages and script messages from, procedure, activity and several other topics.

OET CLI action	Parameters	Default	Description
Listen	server-url	See Configuration section	Get real times scripts events Get a real time delivery of events published by oet server/scripts
wait_for_qa_ready	server-url	See Configuration section	Control QA ready wait behaviour Control whether the OET waits for QA ready before starting a scan. The action must be one of: enable: always wait for QA ready before scanning. Persists until disabled. disable: never wait for QA ready before scanning. Persists until enabled. override: bypass any active QA ready wait for the currently running script, current scan only.
	action	None

Examples

A ‘listen’ command will give the real time delivery of oet events published by scripts:

$ oet listen

event: request.procedure.list
data: args=() kwargs={'msg_src': 'FastAPIWorker', 'request_id': 1604056049.4846392, 'pids': None}

event: procedure.pool.list
data: args=() kwargs={'msg_src': 'SESWorker', 'request_id': 1604056049.4846392, 'result': []}

event: activity.pool.list
data: args=() kwargs={'msg_src': 'ActivityWorker', 'request_id': 1604056078.4847652, 'result': []}

event: request.procedure.create
data: args=() kwargs={'msg_src': 'FastAPIWorker', 'request_id': 1604056247.0666442, 'cmd': PrepareProcessCommand(script_uri='file://scripts/eventbus.py', init_args=<ProcedureInput(, subarray_id=1)>)}

event: procedure.lifecycle.created
data: args=() kwargs={'msg_src': 'SESWorker', 'request_id': 1604056247.0666442, 'result': ProcedureSummary(id=1, script_uri='file://scripts/eventbus.py', script_args={'init': <ProcedureInput(, subarray_id=1)>, 'run': <ProcedureInput(, )>}, history=<ProcessHistory(process_states=[(ProcedureState.READY, 1604056247.713874)], stacktrace=None)>, state=<ProcedureState.READY: 1>)}

Press Control-c to exit from oet listen.

A wait_for_qa_ready command can be used to control whether the OET waits for QA ready before starting a scan:

# Enable waiting for QA ready on subarray 1
$ oet wait_for_qa_ready enable --subarray_id=1
Sent command: always wait for QA before scanning

# Disable waiting for QA ready on subarray 1
$ oet wait_for_qa_ready disable --subarray_id=1
Sent command: never wait for QA before scanning

# Override the QA ready wait for the current scan only
$ oet wait_for_qa_ready override --subarray_id=1
Sent command: bypass any active wait for QA

Procedure

Using oet procedure, a remote OET deployment can be instructed to:

1. load a Python script using oet procedure create;

2. run a function contained in the Python script using oet procedure start;

3. stop a running Python function using oet procedure stop;

In addition, the current and historic state of Python processes running on the backend can be inspected with

1. oet procedure list to list all scripts that are prepared to run or are currently running;

2. oet procedure describe to inspect the current and historic state of a specific process.

The commands available via oet procedure are described below.

OET CLI action	Parameters	Default	Description
create	server-url	See Configuration section	Prepare a new procedure Load the requested script and prepare it for execution. Arguments provided here are passed to the script init function, if defined OET maintains record of 10 newest scripts which means creating 11th script will remove the oldest script from the record.
	script-uri	None
	args	None
	kwargs	--subarray_id=1 --git_repo= “https://gitlab.com/ska-telescope/oso/ska-oso-scripting.git” --git_branch=”master” --git_commit=None --create_env=False
list	server-url	See Configuration section	List procedures Return info on the collection of 10 newest procedures, or info on the one specified by process ID (pid)
	pid	None
start	server-url	See Configuration section	Start a Procedure Executing Start a process executing the procedure specified by process ID (pid) or, if none is specified start the last one loaded. Only one procedure can be executing at any time. listen flag is set to True by default which means that events are shown on the command line unless is is explicitly set to False.
	pid	None
	args	None
	kwargs	None
	listen	True
stop	server-url	See Configuration section	Stop Procedure Execution Stop a running process executing the procedure specified by process ID (pid) or, if none is specified, stop the currently running process. If run_abort flag is True, OET will send Abort command to the SubArray as part of script termination.
	pid	None
	run_abort	True
describe	server-url	See Configuration section	Investigate a procedure Displays the call arguments, state history and, if the procedure failed, the stack trace of a specified process ID (pid). If no pid is specified describe the last process created.
	pid	None

In the table ‘args’ refers to parameters specified by position on the command line, ‘kwargs’ to those specified by name e.g. –myparam=12.

Examples

Create a new Procedure in the OET using a script on the filesystem:

$ oet procedure create file://<file path>.py 'some arg'

  ID  Script           Creation time        State
----  ---------------  -------------------  -------
   1  file://test.py   2020-09-30 10:30:12  CREATING

Create a new Procedure in the OET using a script from Git:

$ oet procedure create git://<path from repo root>.py --git_repo="https://<git repo>.git" --git_branch="test" --create_env=True

 ID   Script           Creation time        State
----  ---------------  -------------------  -------
  3  git://test3.py    2020-09-30 10:40:12  CREATING

Check the state of the Procedures currently loaded:

$ oet procedure list

 ID   Script           Creation time        State
----  ---------------  -------------------  -------
   1  file://test.py   2020-09-30 10:30:12  READY
   2  file://test2.py  2020-09-30 10:35:12  READY
   3  git://test3.py   2020-09-30 10:40:12  READY

Start a the running of a Procedure:

$ oet procedure start --pid=2 'bob' --simulate=false

  ID   Script           Creation time        State
----  ---------------  -------------------  -------
  2   file://test2.py  2020-09-30 10:35:12  RUNNING

See details of a Procedure:

$ oet procedure describe --pid=2

   ID  Script           URI
 ----  ---------------  -----------------------------------------
    2  file://test2.py  http://0.0.0.0:5000/ska-oso-oet/oet/api/v1/procedures/2

 Time                        State
 --------------------------  -------
 2020-09-30 10:19:38.011584  CREATING
 2020-09-30 10:19:38.016266  IDLE
 2020-09-30 10:19:38.017883  LOADING
 2020-09-30 10:19:38.018880  IDLE
 2020-09-30 10:19:38.019006  RUNNING 1
 2020-09-30 10:19:38.019021  READY
 2020-09-30 10:35:12.605270  RUNNING 2

 Index     Method     Arguments    Keyword Arguments
 --------  ---------  -----------  -------------------
     1      init      ['goodbye']  {'subarray_id': 1}
     2      run       ['bob']      {'simulate': false}

Activity

Using oet activity, a remote OET deployment can be instructed to:

1. execute a observing activity of a Scheduling Block with oet activity run

In addition, the current and historic state of Activities can be inspected with

1. oet activity list to list all activities that have been started;

2. oet activity describe to inspect the current and historic state of a specific activity.

The commands available via oet activity are described below.

OET CLI action	Parameters	Default	Description
run	server-url	See Configuration section	Run an activity of an SB Create and run a script referenced by an activity defined in an SB. The activity-name and sbd-id are mandatory arguments. script-args is a dictionary defining function name as a key (e.g. ‘init’) and any keyword arguments to be passed for the function on top of arguments present in the SB. Only keyword args are currently allowed. preparep-only should be set to False if the script referred to by SB and activity is not to be run yet. To start a prepared script, use the oet procedure commands. create-env flag should be set to True if script referred to by SB is a Git script and requires a non- default environment to run.
	activity-name	None
	sbd-id	None
	script-args	None
	prepare-only	False
	create-env	False
	listen	True
list	server-url	See Configuration section	List activities Return info on the collection of 10 newest activities, or info on the one specified by activity ID (aid)
	aid	None
describe	server-url	See note above	Investigate an activity Displays the script arguments, and the state history of a specified activity ID (aid). If no aid is specified describe the last activity created.
	aid	None

The activity name is given in the SBD and although this can be set to anything in the PDM, a typical observation was envisaged as having multiple activities, including allocate (assign resources) and observe (configure and then run a scan). It is now assumed that only one script will be used and OSO Scripting, for example, now only contains a single script, allocate_and_observe.py. This could be given any activity name, with observe probably being the best choice.

One reason for only wanting to run one activity per SBD is that currently each would create a separate Scheduling Block Instance (SBI) as the OET has no state management that allows it to link different activities taking place as part of the same SBD. This might change in the future.

Examples

Running an Activity with name observe inside SBDefinition sbd-123 with run time arguments passed into the script:

$ oet activity run observe sbd-123 --script-args='{"init": {"kwargs": {"foo": "bar"}}}'

  ID  Activity    SB ID    Creation Time          Procedure ID  State
----  ----------  -------  -------------------  --------------  ---------
   1  observe     sbd-123  2023-01-06 13:56:47               1  REQUESTED

Note the use of keyword arguments for the script arguments. These will be passed as arguments when each function in the script is run. If the given keyword argument is already defined in the Scheduling Block, the value will be overwritten with the user provided one.

See details of an Activity:

$ oet activity describe --aid=1

   ID  Activity    SB ID      Procedure ID  State
 ----  ----------  -------  --------------  ---------
    1  observe     sbd-123               1  COMPLETE

 URI                                        Prepare Only
 -----------------------------------------  --------------
 http://0.0.0.0:5000/ska-oso-oet/oet/api/v1/activities/1  False

 Time                        State
 --------------------------  ---------
 2023-01-06 13:56:47.655175  REQUESTED
 2023-01-06 13:56:47.934723  PREPARED
 2023-01-06 13:56:48.004753  RUNNING
 2023-01-06 13:56:50.382756  COMPLETE


 Script Arguments
 ----------------

 Method    Arguments    Keyword Arguments
 --------  -----------  -------------------
 init      [1, 'foo']   {'foo': 'bar'}