Once a BOS session template is created, users can perform operations on nodes,
such as boot, reboot, and shutdown.
To find the corresponding API calls for any Cray CLI command, append -vvv to the end of the CLI command.
This makes the CLI print the underlying API call in the output.
Creating a new BOS v2 session requires the following command-line options:
--template-name: Use this option to specify the name value returned in the cray bos v2 sessiontemplates list command.--operation: Use this option to indicate if a boot, reboot, or shutdown action is being taken.(ncn-mw#): The following is a boot operation:
cray bos v2 sessions create --template-name <TEMPLATE_NAME> --operation boot --format json
Example output:
{
"components": "",
"include_disabled": false,
"limit": "",
"name": "9fea7f3f-0a77-40b9-892d-37712de51d65",
"operation": "boot",
"stage": false,
"status": {
"end_time": null,
"error": null,
"start_time": "2022-08-22T14:44:27",
"status": "pending"
},
"template_name": "TEMPLATE_NAME",
"tenant": null
}
BOS v2 sessions also support several other optional arguments:
--name: The session name can be specified. If not set, a random UUID will be generated for the name.--limit: Limits the nodes that BOS will run against.
session_limit_required BOS option is enabled, then the limit argument is not optional.--stage: Sets staged_state for components rather than desired_state.
--include-disabled: BOS sessions automatically exclude nodes that have been disabled in the
Hardware State Manager (HSM),
unless this argument is set to true when the session is created.Creating a new BOS v1 session requires the following command-line options:
--template-name: Use this option to specify the name value returned in the cray bos v1 sessiontemplate list command.--operation: Use this option to indicate if a boot, reboot, configure, or shutdown action is being taken.(ncn-mw#): The following is a boot operation:
cray bos v1 session create --template-name <TEMPLATE_NAME> --operation boot --format json
Example output:
{
"job": "boa-9173f29f-29a4-424f-b974-7fe85036dc3f",
"limit": "",
"links": [
{
"href": "/v1/session/9173f29f-29a4-424f-b974-7fe85036dc3f",
"jobId": "boa-9173f29f-29a4-424f-b974-7fe85036dc3f",
"rel": "session",
"type": "GET"
},
{
"href": "/v1/session/9173f29f-29a4-424f-b974-7fe85036dc3f/status",
"rel": "status",
"type": "GET"
}
],
"operation": "boot",
"templateName": "TEMPLATE_NAME"
}
The BOS v1 session ID is a UUID embedded in the job, jobId, and href fields.
In the above example, it is 9173f29f-29a4-424f-b974-7fe85036dc3f.
BOS v1 sessions also support the following optional argument:
--limit: Limits the nodes that BOS will run against.
session_limit_required BOS v2 option has no impact on v1 sessions.It is important to periodically delete completed BOS v1 sessions. If too many BOS v1 sessions exist, it can lead to hangs when trying to list them. This limitation does not exist in BOS v2. For more information, see:
(ncn-mw#) List all BOS v2 sessions with the following command:
cray bos v2 sessions list --format json
Example output:
[
{
"components": "",
"include_disabled": false,
"limit": "",
"name": "9fea7f3f-0a77-40b9-892d-37712de51d65",
"operation": "boot",
"stage": false,
"status": {
"end_time": null,
"error": null,
"start_time": "2022-08-22T14:44:27",
"status": "pending"
},
"template_name": "cle-1.1.0",
"tenant": null
}
]
(ncn-mw#) List all BOS v1 sessions with the following command:
cray bos v1 session list --format json
Example output:
[
"34dddd18-1f53-4fd7-829e-3ac7b4e995c3",
"ebe82079-2397-4e03-8e39-091a8d036146"
]
Troubleshooting: There is a known limitation of BOS v1 that listing sessions will hang if too many sessions exist. For more information, see Hang Listing BOS V1 Sessions.
(ncn-mw#) Get details for a BOS v2 session using the session name.
cray bos v2 sessions describe <BOS_SESSION_NAME> --format json
Example output:
{
"components": "",
"include_disabled": false,
"limit": "",
"name": "9fea7f3f-0a77-40b9-892d-37712de51d65",
"operation": "boot",
"stage": false,
"status": {
"end_time": null,
"error": null,
"start_time": "2022-08-22T14:44:27",
"status": "pending"
},
"template_name": "cle-1.1.0",
"tenant": null
}
(ncn-mw#) Get details for a BOS v1 session using the session ID.
cray bos v1 session describe <BOS_SESSION_ID> --format json
Example output:
{
"complete": false,
"error_count": 0,
"in_progress": false,
"job": "boa-34dddd18-1f53-4fd7-829e-3ac7b4e995c3",
"operation": "reboot",
"start_time": "2022-08-22T12:22:33.708209Z",
"status_link": "/v1/session/34dddd18-1f53-4fd7-829e-3ac7b4e995c3/status",
"stop_time": "2022-08-22 12:58:23.674867",
"templateName": "cle-1.1.0"
}
Troubleshooting: There is a known issue in BOS v1 where some sessions cannot be described using the cray bos v1 session describe command.
The issue with the describe action results in a 404 error, despite the session existing in the output of cray bos v1 session list command.
(ncn-mw#) View the status of a BOS session using the session name.
cray bos v2 sessions status list <BOS_SESSION_NAME> --format json
See View the status of a v2 session.
See View the status of a v1 session.
(ncn-mw#) Delete a specific BOS v2 session:
cray bos v2 sessions delete <BOS_SESSION_NAME>
It is important to periodically delete completed BOS v1 sessions. If too many BOS v1 sessions exist, it can lead to hangs when trying to list them. This limitation does not exist in BOS v2. For more information, see Hang Listing BOS V1 Sessions.
(ncn-mw#) Delete a specific BOS v1 session:
cray bos v1 session delete <BOS_SESSION_ID>
In CSM 1.5.0 on large systems, BOS v2 sessions may not work properly because of a failed interaction with CFS. For more information, see CFS V2 Failures On Large Systems.