The Regional Controller's Object Model
The Regional Controller performs its work by maintaining an Object Model. The Object Model consists of a number of objects, described below, which model the machines, software, and lifecycles of the various Akraino deployments that the Regional Controller controls. The collection of all the objects that the Regional Controller maintains in this model, as well as their relationships is know as the Akraino Universe.
...
A set of functionality that can be assigned to one or more Users. Roles allow users to perform specific functions within the API. The roles are hard-coded into the Regional Controller, and are not expected to change often, if at all; as such, there are no CRUD operations defined for the roles. A user of the API can discover what roles s/he has been given via the Login API.
Flow of Operation
An example of how the API would be used to deploy a POD on a bunch of new machines follows. These examples use curl as that is the most compact way to show all of the required headers and data elements required. Of course, any other programming language may also be used.
Get a Login Token
You will need an account that has permissions to create Nodes, Edgesites, and PODs (and possibly Blueprints too, if you are defining a new Blueprint). To do this use the Login API as follows (assuming the login is admin and password abc123):
| Code Block |
|---|
|
$ curl -v -k -H 'Content-Type: application/yaml' --data '{ name: admin, password: abc123 }' https://arc.akraino.demo/api/v1/login |
The API will return a login token (which will expire in one hour) in the X-ARC-Token header. This should be passed to all subsequent API calls.
| Code Block |
|---|
|
X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ== |
Enumerate the Machines
Assuming the machines to deploy on have not yet been made known to the RC, you would need to use the Node API to add them to the RC database.
Do this with the following API call, once per node:
| Code Block |
|---|
|
$ YAML='{
name: nodename,
description: a description of the node,
hardware: <hardware profile UUID>
}'
$ curl -v -k -H 'Content-Type: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' \
--data "$YAML" https://arc.akraino.demo/api/v1/node |
Keep track of the UUID of each node that is returned from the API.
Create an Edge Site
Once the nodes are defined, you need to create an Edge Site (a cluster of nodes). Do this:
| Code Block |
|---|
|
$ YAML='{
name: edgesitename,
description: description of the Edgesite,
nodes: [ <list of node UUIDs> ],
regions: [ <list of region UUIDs> ]
}'
$ curl -v -k -H 'Content-Type: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' \
--data "$YAML" https://arc.akraino.demo/api/v1/edgesite |
Create/Verify the Blueprint
To get the UUID of the Blueprint, you would need to see which Blueprints are installed:
| Code Block |
|---|
|
$ curl -v -k -H 'Accept: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' https://arc.akraino.demo/api/v1/blueprint |
If the Blueprint you want is missing, you may need to create it:
| Code Block |
|---|
|
$ YAML='{
blueprint: 1.0.0,
name: my new blueprint,
version: 1.0.0,
description: description of the blueprint,
yaml: ....
}'
$ curl -v -k -H 'Content-Type: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' \
--data "$YAML" https://arc.akraino.demo/api/v1/blueprint |
Start the Deployment (Create the POD)
Start the deployment by creating a POD:
| Code Block |
|---|
|
$ YAML='{
name: my new POD,
description: description of this POD,
blueprint: 827cfe84-2e28-11e9-bb34-0017f20dbff8,
edgesite: 2d3533e4-3dcb-11e9-9533-87ac04f6a7e6
}'
$ curl -v -k -H 'Content-Type: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' \
--data "$YAML" https://arc.akraino.demo/api/v1/pod |
Make note of the UUID that is returned. You will need it to monitor the deployment.
Monitor the deployment by monitoring the POD Event URL for the newly created POD. This will return a list of events related to the POD similar to:
| Code Block |
|---|
|
$ curl -v -k -H 'Accept: application/yaml' -H 'X-ARC-Token: YWRtaW4gICAgICAgIDE1NTY1NTgyMjExMzQ4N2NmMGUwNQ==' \
https://arc.akraino.demo/api/v1/podevent/56b365a0-d6a2-4d12-8f02-e2fc2671573e
events:
- {level: INFO, time: '2019-04-29 18:15:28.0', message: Pod created.}
- {level: INFO, time: '2019-04-29 18:15:28.0', message: 'Starting workflow: create'}
- {level: INFO, time: '2019-04-29 18:15:28.0', message: 'Workflow directory created:
$DROOT/workflow/create-56b365a0-d6a2-4d12-8f02-e2fc2671573e'}
- {level: WARN, time: '2019-04-29 18:17:38.0', message: 'Could not fetch the workflow
file http://example.com/blueprints/create.py'} |
Flow of Operation using CLI commands
The equivalent of the previous section, using the CLI command rc_cli would be:
Enumerate the Machines
Assuming the machines to deploy on have not yet been made known to the RC, you would need to use the Node API to add them to the RC database.
Do this with the following API call, once per node:
| Code Block |
|---|
|
$ cat > node.yaml <<EOF
name: nodename
description: a description of the node
hardware: <hardware profile UUID>
EOF
$ rc_cli -u admin -p abc123 node create node.yaml |
Keep track of the UUID of each node that is returned from the API.
Create an Edge Site
Once the nodes are defined, you need to create an Edge Site (a cluster of nodes). Do this:
| Code Block |
|---|
|
$ cat > es.yaml <<EOF
name: edgesitename
description: a description of the Edgesite
nodes: [ <list of node UUIDs> ]
regions: [ <list of region UUIDs> ]
EOF
$ rc_cli -u admin -p abc123 edgesite create es.yaml |
Create/Verify the Blueprint
To get the UUID of the Blueprint, you would need to see which Blueprints are installed:
| Code Block |
|---|
|
$ rc_cli -u admin -p abc123 blueprint list |
If the Blueprint you want is missing, you may need to create it:
| Code Block |
|---|
|
$ cat > blueprint.yaml <<EOF
blueprint: 1.0.0
name: my new blueprint
version: 1.0.0
description: description of the blueprint
yaml: ....
EOF
$ rc_cli -u admin -p abc123 blueprint create blueprint.yaml |
Start the Deployment (Create the POD)
Start the deployment by creating a POD:
| Code Block |
|---|
|
$ cat > pod.yaml <<EOF
name: my new POD
description: description of this POD
blueprint: 827cfe84-2e28-11e9-bb34-0017f20dbff8
edgesite: 2d3533e4-3dcb-11e9-9533-87ac04f6a7e6
EOF
$ rc_cli -u admin -p abc123 pod create pod.yaml |
Make note of the UUID that is returned. You will need it to monitor the deployment.
Monitor the deployment by displaying the newly created POD. Note: the rc_cli command does not presently interface to the POD event API, so this will not be precisely equivalent to the curl calls shown above. This will return a list of events related to the POD similar to:
| Code Block |
|---|
|
$ ./rc_cli -H rc -p admin123 pod show d72e1901-b9b3-4137-b217-fc3cae4575ac
---
blueprint: 690450c0-776a-11e9-ae9b-f3cee2e49e42
description: CD of blueprint on OE
edgesite: 60ab1298-7769-11e9-92b3-373d9b2f2476
events:
- level: INFO
message: Pod created.
time: '2019-06-13 16:56:19.0'
- level: INFO
message: 'Starting workflow: create'
time: '2019-06-13 16:56:19.0'
- level: INFO
message: 'Workflow directory created: $DROOT/workflow/create-0-d72e1901-b9b3-4137-b217-fc3cae4575ac'
time: '2019-06-13 16:56:19.0'
- level: INFO
message: 'Workflow fetched: http://www.example.org/blueprints/work-flow-v0.1.sh'
time: '2019-06-13 16:56:19.0'
- level: INFO
message: Workflow template created.
time: '2019-06-13 16:56:19.0'
- level: INFO
message: Starting create workflow for POD d72e1901-b9b3-4137-b217-fc3cae4575ac
time: '2019-06-13 16:57:02.0'
name: pod_on_oe1
state: WORKFLOW
url: /api/v1/pod/d72e1901-b9b3-4137-b217-fc3cae4575ac
uuid: d72e1901-b9b3-4137-b217-fc3cae4575ac
workflows:
- create
yaml:
input_yaml: http://www.example.org/mtlab/aknode201-user_config.yaml
iso_primary: http://www.example.org/iso/latest/install.iso
iso_secondary: http://www.example.org/iso/latest/bootcd.iso |