Build Hello World Actor¶
Let us build our hello-world actor!
Create a New Actor¶
The function of an actor is exposed as the default command in a Docker container. Here, we will create an actor from an existing Docker container image called tacc/hello-world:1.0 available on Docker Hub. The default command for this container simply prints the message “Hello, World” or the message sent to it, which will be captured in the actor logs.
Create the actor as:
$ tapis actors create --repo tacc/hello-world:1.0 \
-n hello-world-actor \
-d "Test actor that says Hello, World"
+----------------+-----------------------------+
| Field | Value |
+----------------+-----------------------------+
| id | NN5N0kGDvZQpA |
| name | hello-world-actor |
| owner | taccuser |
| image | tacc/hello-world:1.0 |
| lastUpdateTime | 2021-07-14T22:25:06.171534 |
| status | SUBMITTED |
| cronOn | False |
+----------------+-----------------------------+
The --repo flag points to the Docker Hub repo on which this actor is based,
the -n flag and -d flag attach a human-readable name and description to
the actor.
The resulting actor is assigned an id: NN5N0kGDvZQpA. The actor id can be
queried by:
$ tapis actors show NN5N0kGDvZQpA
+-----------------+-----------------------------------+
| Field | Value |
+-----------------+-----------------------------------+
| id | NN5N0kGDvZQpA |
| name | hello-world-actor |
| description | Test actor that says Hello, World |
| owner | taccuser |
| image | tacc/hello-world:1.0 |
| createTime | 2021-09-21T20:05:10.738Z |
| lastUpdateTime | 2021-09-21T20:05:10.738Z |
| gid | 859336 |
| link | |
| privileged | False |
| queue | default |
| stateless | True |
| status | READY |
| statusMessage | |
| token | True |
| uid | 859336 |
| useContainerUid | False |
| webhook | |
| cronOn | False |
| cronSchedule | None |
+-----------------+-----------------------------------+
Above, you can see the plain text name, description that were passed on the command line. In addition, you can see the “status” of the actor is “READY”, meaning it is ready to receive and act on messages. Finally, you can list all actors visible to you with:
$ tapis actors list
+---------------+-------------------+----------+-----------------------------+----------------------------+--------+-------+
| id | name | owner | image | lastUpdateTime | status | cronOn|
+---------------+-------------------+----------+-----------------------------+----------------------------+--------+-------+
| NN5N0kGDvZQpA | hello-word-actor | taccuser | tacc/hello-world:1.0 | 2021-07-14T22:25:06.171Z | READY | False |
+---------------+-------------------+----------+-----------------------------+----------------------------+--------+-------+
Submit a Message to the Actor¶
Next, let’s craft a simple message to send to the reactor. Messages can be plain text or in JSON format. When using the python actor libraries as in the example above, JSON-formatted messages are made available as python dictionaries.
# Submit the message to the actor
$ tapis actors submit -m "Hello, World" NN5N0kGDvZQpA
+-------------+---------------+
| Field | Value |
+-------------+---------------+
| executionId | N4xQ5WM5Np1X0 |
| msg | Hello, World |
+-------------+---------------+
The id of the actor (N4xQ5WM5Np1X0) was used on the command line to specify
which actor should receive the message. In response, an “execution id”
(N4xQ5WM5Np1X0) is returned. An execution is a specific instance of an actor.
List all the executions for a given actor as:
$ tapis actors execs list NN5N0kGDvZQpA
+---------------+----------+
| executionId | status |
+---------------+----------+
| N4xQ5WM5Np1X0 | COMPLETE |
+---------------+----------+
Show detailed information for the execution with:
$ tapis actors execs show -v NN5N0kGDvZQpA N4xQ5WM5Np1X0
{
"actorId": "NN5N0kGDvZQpA",
"apiServer": "https://api.tacc.utexas.edu",
"cpu": 121748743,
"exitCode": 0,
"finalState": {
"Dead": false,
"Error": "",
"ExitCode": 0,
"FinishedAt": "2021-07-14T22:32:45.602Z",
"OOMKilled": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": false,
"StartedAt": "2021-07-14T22:32:45.223Z",
"Status": "exited"
},
"id": "N4xQ5WM5Np1X0",
"io": 176,
"messageReceivedTime": "2021-07-14T22:32:37.051Z",
"runtime": 1,
"startTime": "2021-07-14T22:32:44.752Z",
"status": "COMPLETE",
"workerId": "JABKl4BeDwXJD",
"_links": {
"logs": "https://api.tacc.utexas.edu/actors/v2/NN5N0kGDvZQpA/executions/N4xQ5WM5Np1X0/logs",
"owner": "https://api.tacc.utexas.edu/profiles/v2/sgopal",
"self": "https://api.tacc.utexas.edu/actors/v2/NN5N0kGDvZQpA/executions/N4xQ5WM5Np1X0"
}
}
We can see here that the above execution has already completed.
Check the Logs for an Execution¶
An execution’s logs will contain whatever was printed to STDOUT / STDERR by the actor. In our demo actor, we just expect the actor to print the message passed to it.
$ tapis actors execs logs NN5N0kGDvZQpA N4xQ5WM5Np1X0
Logs for execution N4xQ5WM5Np1X0
Actor received message: Hello, World
In a normal scenario, the actor would then act on the contents of a message to, e.g., kick off a job, perform some data management, send messages to other actors, or more.
Run Synchronously¶
The previous message submission (with tapis actors submit) was an
asynchronous run, meaning the command prompt detached from the process after
it was submitted to the actor. In that case, it was up to us to check the execution
to see if it had completed and manually print the logs.
There is also a mode to run actors synchronously using tapis actors run,
meaning the command line stays attached to the process awaiting a response after
sending a message to the actor.
Delete and Update an Actor¶
Actors can be deleted with the following:
$ tapis actors delete NN5N0kGDvZQpA
+----------+-------------------+
| Field | Value |
+----------+-------------------+
| deleted | ['NN5N0kGDvZQpA'] |
| messages | [] |
+----------+-------------------+
This will delete the actor and any associated executions.
Actors can also be updated with the tapis actors update command to make changes once created.
Need help? Ask your questions using the [TACCSTER 2021 Slack Workspace] using the #tutorial-automating-work-at-tacc-with-tapis-actors channel.