| layout | title | tagline |
|---|---|---|
page |
Abaco CLI Basics |
The Abaco CLI is a command line interface for working with actor based containers. Also called actors or reactors, these are arbitrary, containerized executables or instructions that can be triggered in response to an event.
The introduction to the Abaco CLI below is adapted from the tutorial found here.
#### Installation and set up
If you have already installed the SD2E CLI and set up
authorization tokens, then no further set up is required.
Test that abaco is in your path by typing:
% abaco
Usage: abaco [COMMAND] [OPTION]...
Set of commands for interacting with Abaco API. Options vary by
command; use -h flag after command to view usage details.
Commands:
list, ls, actors, images list actors
create, make, register create new actor
delete, remove, rm remove actor
update, change update base Docker image
permissions, share list and update actor permissions
workers, worker view and add workers
submit, run run actor
executions view actor executions
logs view execution logs
init create a new actor project
deploy build and deploy an actor
#### Command summary
As seen above, issuing 'abaco' on an empty line will show the command summary.
Help text for each command can be viewed with the -h flag. For example:
% abaco list -h
Usage: abaco list [OPTION]...
abaco list [OPTION]... [ACTORID]
Returns list of actor names, IDs, and statuses or JSON description of
actor if ID provided
Options:
-h show help message
-z api access token
-v verbose output
-V very verbose output
#### Create and run an actor
At the core of a actor is a Docker container. Here, we will spin up an
instance of a Docker image called jturcino/abaco-trial available on
Docker Hub. The entrypoint
for this container simply prints some information in the current environment to
standard out, which will be captured in the actor logs.
First, create a actor named example-actor and pass in environment variables
with the -e flag:
% abaco create -n example-actor -e foo=bar -e bar=baz jturcino/abaco-trial:latest
example-actor 5v165gLJwWmR6
The command 'abaco list' can be used to check the actor's status. Provide the
actor ID to get a more detailed description:
% abaco list
example-actor 5v165gLJwWmR6 READY
% abaco list 5v165gLJwWmR6
{
"message": "Actor retrieved successfully.",
"result": {
"_links": {
"executions": "https://api.sd2e.org/actors/v2/5v165gLJwWmR6/executions",
"owner": "https://api.sd2e.org/profiles/v2/username",
"self": "https://api.sd2e.org/actors/v2/5v165gLJwWmR6"
},
"createTime": "2018-04-27 17:28:38.482897",
"defaultEnvironment": {
"bar": "baz",
"foo": "bar"
},
"description": "",
"gid": 827385,
"id": "5v165gLJwWmR6",
"image": "jturcino/abaco-trial:latest",
"lastUpdateTime": "2018-04-27 17:28:38.482897",
"mounts": [
{
"container_path": "/work",
"host_path": "/work",
"mode": "rw"
},
{
"container_path": "/corral",
"host_path": "/corral-repl/projects/SD2E-Community",
"mode": "rw"
}
],
"name": "example-actor",
"owner": "username",
"privileged": false,
"state": {},
"stateless": false,
"status": "READY",
"statusMessage": " ",
"tasdir": "01234/username",
"type": "none",
"uid": 827385,
"useContainerUid": false
},
"status": "success",
"version": "0.6.0"
}
Once the status is READY, run the actor with 'abaco submit'. It is required to
pass a message to the actor with the -m flag, which will be added to the
environment:
% export MESSAGE='{"key1":"value1", "key2":"value2"}'
% abaco submit -m "$MESSAGE" 5v165gLJwWmR6
gAbVREpGeE1VY
{
"key1": "value1",
"key2": "value2"
}
When an actor is run, an execution ID is returned along with the contents of
the input message.
#### Check execution status, workers, and logs
Abaco 'executions' are conceptually similar to Agave 'jobs'. You can check the list of executions run against a specific actor by performing:
% abaco executions 5v165gLJwWmR6
gAbVREpGeE1VY
The status of a specific execution can be found by providing its ID as well:
% abaco executions 5v165gLJwWmR6 gAbVREpGeE1VY
kQVAMo38XDKZw COMPLETE
The other ID returned (kQVAMo38XDKZw) is known as the worker ID for the
actor. By default, each actor is only assigned one worker, meaning it can only
handle one process at a time (additional processes are queued). The full list of
workers associated with an actor and their current status can be found using the
abaco workers command:
% abaco workers 5v165gLJwWmR6
kQVAMo38XDKZw READY
Finally, you can bring up the logs of a specific execution by providing the actor ID and execution ID:
% abaco logs 5v165gLJwWmR6 gAbVREpGeE1VY
Logs for execution gAbVREpGeE1VY:
FULL CONTEXT:
{
"username": "username",
"_abaco_jwt_header_name": "X-Jwt-Assertion-Sd2E",
"_abaco_actor_id": "5v165gLJwWmR6",
"raw_message": "{'key1': 'value1', 'key2': 'value2'}",
"actor_dbid": "SD2E_5v165gLJwWmR6",
"_abaco_actor_state": "{}",
"content_type": null,
"PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"MSG": "{'key1': 'value1', 'key2': 'value2'}",
"bar": "baz",
"_abaco_api_server": "https://api.sd2e.org",
"_abaco_Content_Type": "application/json",
"execution_id": "gAbVREpGeE1VY",
"_abaco_access_token": "5bcbe4e649c9103522c08e25133cb",
"message_dict": {
"key2": "value2",
"key1": "value1"
},
"_abaco_actor_dbid": "SD2E_5v165gLJwWmR6",
"HOSTNAME": "c5f6fa87c8eb",
"_abaco_execution_id": "gAbVREpGeE1VY",
"state": "{}",
"_abaco_username": "username",
"actor_id": "5v165gLJwWmR6",
"foo": "bar",
"HOME": "/"
}
MESSAGE:
{
"key2": "value2",
"key1": "value1"
}
FULL ENVIRONMENT:
{
"_abaco_actor_state": "{}",
"foo": "bar",
"bar": "baz",
"_abaco_actor_dbid": "SD2E_5v165gLJwWmR6",
"HOSTNAME": "c5f6fa87c8eb",
"_abaco_execution_id": "gAbVREpGeE1VY",
"_abaco_username": "username",
"_abaco_actor_id": "5v165gLJwWmR6",
"_abaco_access_token": "5bcbe4e649c9103522c08e25133cb",
"MSG": "{'key1': 'value1', 'key2': 'value2'}",
"PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"_abaco_api_server": "https://api.sd2e.org",
"HOME": "/",
"_abaco_Content_Type": "application/json",
"_abaco_jwt_header_name": "X-Jwt-Assertion-Sd2E"
}
ROOT FILES:
bin boot dev etc home lib lib64 media mnt opt proc root run sbin srv sys tmp usr
var agavepy script.py requirements.txt .dockerenv work corral _abaco_results.sock
corral-repl
In the job logs you will find the environment variables that were defined when the actor was created, and variables that were passed via message when the specific instance of the actor was executed.
#### Modify, share, and delete an actor
When the base image behind an actor is re-tagged, the actor can be updated to use the newer version. For example:
% abaco update -i jturcino/abaco-trial:update 5v165gLJwWmR6
example-actor 5v165gLJwWmR6
% abaco list 5v165gLJwWmR6
...
"image": "jturcino/abaco-trial:update",
...
Similar to Agave apps, abaco actors can be shared with
other users on the SD2E tenant. For example, to share your actor with a user
named my_collaborator, perform:
% abaco permissions -u my_collaborator -p EXECUTE 5v165gLJwWmR6
my_collaborator EXECUTE
username UPDATE
Valid permission levels are NONE, READ, EXECUTE, and UPDATE.
Finally, actors can be deleted with the 'abaco delete' command:
% abaco delete 5v165gLJwWmR6
Actor deleted successfully.
Return to the API Documentation Overview