Boot Script Service v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Boot Script Service (BSS) manages the iPXE boot scripts that coordinate the boot process for nodes, and enables basic association of boot scripts with nodes. When nodes initially power on, boot, or reboot, they consult BSS for their target artifacts and boot parameters. The boot scripts are generated on demand from the information that is entered and delivered to the requester during an iPXE boot. The boot scripts supply a booting node with a pointer to the necessary images (kernel and initrd) that are stored in the artifact repository and a set of boot-time parameters. The BSS API allows the caller to retrieve an iPXE boot script from the boot script server, and to set, update, delete, and retrieve boot script parameters for each host in a system. BSS works with all nodes that are known to HSM and do not have the hardware role as Management in HSM.

Resources

/boot/v1/bootscript

Retrieve the iPXE boot script for a host. One of the three parameters is required - name, MAC, or NID.

/boot/v1/bootparameters

Set, update, delete, and retrieve boot script parameters for specific hosts.

/boot/v1/hosts

Retrieve the latest host information like state, NID, and ID from HSM.

/boot/v1/dumpstate

Dump internal state of boot script service for debugging purposes.

Workflows

Define Boot Parameters for all Nodes

POST /boot/v1/bootparameters

Define boot parameters. Specify the host as Default. While BSS allows for fine grained control of individual nodes, the Default tag is typically more convenient, especially for a large system.

Along with the host, the kernel, initrd, and params should be defined. The kernel is required for BSS to generate a boot script, but initrd and params are typically needed for the node to boot successfully. The kernel and initrd fields contain a URL to the respective images. The params field is a string that will be passed to the kernel during the boot process.

GET /boot/v1/bootscript

Verify the boot script to ensure it’s what you want

Update Boot Parameters

GET /boot/v1/hosts

Retrieve list of hosts known to HSM and select the host for which the boot parameters need to be changed.

GET /boot/v1/bootparameters

Retrieve the boot parameters for the specific host.

PUT /boot/v1/bootparameters

Update boot parameters for the host.

GET /boot/v1/bootparameters

Verify the boot parameters for the specific host.

Base URLs:

Authentication

  • HTTP Authentication, scheme: bearer

cli_ignore

meta_data_get

Code samples

GET https://api-gw-service-nmn.local/apis/bss/meta-data HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/meta-data \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/meta-data', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/meta-data", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /meta-data

Retrieve cloud-init meta-data

Parameters

Name In Type Required Description
key query string false Specific sub key(s) to query. Separated by periods.

Example responses

200 Response

{}

Responses

Status Meaning Description Schema
200 OK meta-data for node Inline
400 Bad Request Bad Request Error
404 Not Found Does Not Exist - Either the host, MAC or NID are unknown and there is no Default, or the existing entry does not specify a kernel image for boot. Error
default Default Unexpected error Error

Response Schema

To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

user_data_get

Code samples

GET https://api-gw-service-nmn.local/apis/bss/user-data HTTP/1.1
Host: api-gw-service-nmn.local
Accept: text/yaml

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/user-data \
  -H 'Accept: text/yaml' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'text/yaml',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/user-data', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"text/yaml"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/user-data", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /user-data

Retrieve cloud-init user-data

Example responses

200 Response

Responses

Status Meaning Description Schema
200 OK user-data for node Inline
400 Bad Request Bad Request Error
404 Not Found Does Not Exist - Either the host, MAC or NID are unknown and there is no Default, or the existing entry does not specify a kernel image for boot. Error
default Default Unexpected error Error

Response Schema

To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

phone_home_post

Code samples

POST https://api-gw-service-nmn.local/apis/bss/phone-home HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://api-gw-service-nmn.local/apis/bss/phone-home \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api-gw-service-nmn.local/apis/bss/phone-home', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api-gw-service-nmn.local/apis/bss/phone-home", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /phone-home

Post cloud-init

Body parameter

{
  "pub_key_dsa": "string",
  "pub_key_rsa": "string",
  "pub_key_ecdsa": "string",
  "pub_key_ed25519": "string",
  "instance_id": "string",
  "hostname": "string",
  "fqdn": "string"
}

Parameters

Name In Type Required Description
body body CloudInitPhoneHome false none

Example responses

200 Response

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Responses

Status Meaning Description Schema
200 OK Meta data for node BootParams
400 Bad Request Bad Request Error
404 Not Found Does Not Exist - Either the host, MAC or NID are unknown and there is no Default, or the existing entry does not specify a kernel image for boot. Error
default Default Unexpected error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

bootscript

bootscript_get

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/bootscript HTTP/1.1
Host: api-gw-service-nmn.local
Accept: text/plain

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/bootscript \
  -H 'Accept: text/plain' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'text/plain',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootscript', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"text/plain"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootscript", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/bootscript

Retrieve iPXE boot script

Retrieve iPXE boot script for the host specified by the MAC parameter. Alternatively, for test/convenience purposes, use the name or the NID parameter to specify the host name or xname. Do not specify more than one parameter (MAC, name, or NID) in the request as results are undefined if they do not all refer to the same node.

Parameters

Name In Type Required Description
mac query string false MAC address of host requesting boot script
name query string false Name of host requesting boot script or xname
nid query integer false Node ID (NID) of host requesting boot script
retry query integer false Number of times requesting script without a successful boot. This parameter is mostly used by the software itself to keep track of retries.
arch query string false The architecture value from the iPXE variable ${buildarch}. This parameter is mostly used by the software itself.
ts query integer false Timestamp for when the HSM state info needs to be up to date by. This is the Unix concept of time, the number of seconds since Jan 1, 1970 UTC. This parameter is mostly used by the software itself.

Example responses

200 Response

"#!ipxe\nkernel --name kernel http://rgw-vip.nmn/boot-images/00000000-0000-0000-0000-000000000000/kernel initrd=initrd console=ttyS0,115200 bad_page=panic crashkernel=512M hugepagelist=2m-2g intel_iommu=off intel_pstate=disable iommu.passthrough=on numa_interleave_omit=headless oops=panic pageblock_order=14 rd.neednet=1 rd.retry=10 rd.shell systemd.unified_cgroup_hierarchy=1 ip=dhcp quiet spire_join_token=00000000-0000-0000-0000-000000000000 root=craycps-s3:s3://boot-images/00000000-0000-0000-0000-000000000000/rootfs:00000000000000000000000000000000-000:dvs:api-gw-service-nmn.local:300:hsn0,nmn0:0 nmd_data=url=s3://boot-images/00000000-0000-0000-0000-000000000000/rootfs bos_session_id=000000-0000-0000-0000-000000000000 xname=x3000c0s17b3n0 nid=3 bss_referral_token=00000000-0000-0000-0000-000000000000 ds=nocloud-net;s=http://10.92.100.81:8888/ || goto boot_retry\ninitrd --name initrd http://rgw-vip.nmn/boot-images/00000000-0000-0000-0000-000000000000/initrd || goto boot_retry\nboot || goto boot_retry\n:boot_retry\nsleep 30\nchain https://api-gw-service-nmn.local/apis/bss/boot/v1/bootscript?mac=b4:2e:99:df:eb:bf&retry=1\n"

Responses

Status Meaning Description Schema
200 OK Boot script for requested MAC address string
400 Bad Request Bad Request Error
404 Not Found Does Not Exist - Either the host, MAC, or NID are unknown and there is no Default, or the existing entry does not specify a kernel image for boot. Error
default Default Unexpected error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

bootparameters

get__boot_v1_bootparameters

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/bootparameters

Retrieve boot parameters

Retrieve the boot parameters for one or more hosts. If no parameters are provided, then all known parameters are returned. Filtering can be accomplished by either providing a body of the boot parameters or one of the three query parameters: host names, MAC addresses, and/or NIDs. The body of boot parameters can also provide a kernel or initrd path which will be returned along with any bootparameter settings as well. Alternatively, query parameters name=, mac=, and/or nid= can provide the filtering of individual items or comma-separated lists of items. The response is a list of boot parameter items. These items will include the individual kernel and initrd images, along with any related boot parameters. If filtering parameters are provided, each parameter will provide a result if one exists. Note that the kernel and initrd images are specified with a URL or path. A plain path will result in a TFTP download from this server. If a URL is provided, it can be from any available service which iPXE supports, and any location that the iPXE client has access to.

Body parameter

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Parameters

Name In Type Required Description
name query string false Host name or tag name of boot parameters to return
mac query string false MAC Address of host of boot parameters to return
nid query integer false NID of host of boot parameters to return
body body BootParams false none

Example responses

200 Response

[
  {
    "hosts": [
      "x0c0s2b0n0",
      "x0c0s3b0n0"
    ],
    "macs": [
      "00:40:a6:82:f6:c5",
      "a4:bf:01:3e:c0:a2",
      "00:40:a6:82:f7:0c"
    ],
    "nids": [
      1,
      2,
      3,
      4
    ],
    "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
    "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
    "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
    "cloud-init": {
      "user-data": {
        "foo": "bar"
      },
      "meta-data": {
        "foo": "bar"
      }
    }
  }
]

Responses

Status Meaning Description Schema
200 OK List of currently known boot parameters Inline
400 Bad Request Bad Request - BootParams value incorrect Error
404 Not Found Does Not Exist - Cannot find host, MAC, or NID Error
500 Internal Server Error Internal Server Error Error
default Default Unexpected error Error

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [BootParams] false none [When used as a request body, the caller sets boot parameters and specifies hosts, along with the kernel image path/URL and initrd path/URL. To specify hosts, use one of the three parameters - hosts, MACs, or NIDs. If MAC addresses are used, they are mapped to host names based on information retrieved from the hardware state manager. Likewise, if NIDs are used, they are mapped to host names with the same hardware state manager info. While the expected usage is to specify hosts based on their host names, the “macs” and “nids” alternatives may be more convenient in some contexts.
You can also specify a general tag for hosts. A tag is ‘Default’, or one of the roles that a node may be defined as in the hardware state manager (HSM). Some of the HSM roles like ‘Compute’, ‘Storage’, ‘System’, and ‘Application’ can be specified as hosts and are managed similar to specific hosts. While BSS allows for fine grained control of individual nodes, the tags are typically more convenient, especially for a large system.

Alternatively, if you specify a kernel or initrd image and params, but no host, MAC, or NID, the boot script service will associate the specified params with the specified kernel or initrd image. When used as a response body, identifies the hosts available for booting using either hosts, MACs, or NIDs, depending on which parameter was used in the request.]
» hosts [string] false none host names
» macs [string] false none MAC addresses
» nids [integer] false none Node ID
» params string false none Specific to the kernel that is being booted.
» kernel string false none URL or file system path specifying kernel image.
» initrd string false none URL or file system path specifying initrd image.
» cloud-init CloudInit false none Cloud-Init data for the hosts
»» meta-data CloudInitMetadata false none Cloud-Init Instance Metadata for a host.
»» user-data CloudInitUserData false none Cloud-Init User data for a host.
»» phone-home CloudInitPhoneHome false none Data sent from the Phone Home Cloud-Init module after a host’s boot is complete.
»»» pub_key_dsa string false none none
»»» pub_key_rsa string false none none
»»» pub_key_ecdsa string false none none
»»» pub_key_ed25519 string false none none
»»» instance_id string false none none
»»» hostname string false none none
»»» fqdn string false none none
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

post__boot_v1_bootparameters

Code samples

POST https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X POST https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /boot/v1/bootparameters

Create boot parameters

Define boot parameters. Specify a list of one of the following parameters: hosts, MACs, or NIDs along with the boot parameters to associate with those hosts. You can either use specific hosts or specify a general tag for hosts. Specific hosts can be specified either by a hostname (xname), a NID, or a MAC address. It is recommended to use the xname. Otherwise, a tag can be used for the hosts parameter. A tag is “Default”, or one of the roles that a node may be defined as in the hardware state manager (HSM). Some of the HSM roles like ‘Compute’, ‘Storage’, ‘System’, and ‘Application’ can be specified as hosts and are managed similar to specific hosts. While BSS allows for fine grained control of individual nodes, the tags are typically more convenient, especially for a large system.

Along with the hosts, there must be a kernel image reference in order for the boot script service to be able to generate a boot script. In most cases, there should also be an initrd image reference, unless the kernel being booted is standalone and does not require an initrd image. Finally, the params entry can be used to specify boot parameters for the specified hosts. Note that if there is no existing params entry for a host, a new entry for the host is created. If an entry already exists for the host, this request will fail.

Special entries for HSM roles like ‘Compute’, ‘Storage’ and ‘Application’ can also be specified as hosts, and are managed similar to specific hosts. If an error occurs during the save/update, processing will stop after the first error. Subsequent hosts in the list will not be processed.

Body parameter

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Parameters

Name In Type Required Description
body body BootParams false none

Example responses

400 Response

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Responses

Status Meaning Description Schema
201 Created successfully created boot parameters None
400 Bad Request Bad Request - Invalid BootParams value Error
500 Internal Server Error Internal Server Error Error
default Default Unexpected error Error

Response Headers

Status Header Type Format Description
201 BSS-Referral-Token string The UUID that will be included in the boot script. A new UUID is generated on each POST and PUT request.
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

put__boot_v1_bootparameters

Code samples

PUT https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PUT https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.put('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /boot/v1/bootparameters

Set boot parameters

Set or update boot parameters for one or more hosts. Specify a list of one of the following parameters: hosts, MACs, or NIDs along with the boot parameters to associate with those hosts.

You can either use specific hosts or specify a general tag for hosts. Specific hosts can be specified either by a hostname (xname), a NID, or a MAC address. It is recommended to use the xname. Otherwise, a tag can be used for the hosts parameter. A tag is “Default”, or one of the roles that a node may be defined as in the hardware state manager (HSM). Some of the HSM roles like ‘Compute’, ‘Storage’, ‘System’, and ‘Application’ can be specified as hosts and are managed similar to specific hosts. While BSS allows for fine grained control of individual nodes, the tags are typically more convenient, especially for a large system.

Along with the hosts, there must be a kernel image reference in order for the boot script service to be able to generate a boot script. In most cases, there should also be an initrd image reference, unless the kernel being booted is standalone and does not require an initrd image. Finally, the params entry can be used to specify boot parameters specific to the specified hosts. If there are no boot params stored for one or more hosts, then a new entry for that host will be created. For kernel, initrd and params values, an existing value will be replaced. The params value is a replacement of the existing values. If the params value does not specify one or more values, any existing values are removed. If an error occurs during the save/update, processing will stop after the first error. Subsequent hosts in the list will not be processed.

Body parameter

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Parameters

Name In Type Required Description
body body BootParams false none

Example responses

400 Response

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Responses

Status Meaning Description Schema
200 OK successfully update boot parameters None
400 Bad Request Bad Request - Invalid BootParams value Error
404 Not Found Does Not Exist - Cannot find specified host, MAC, or NID Error
500 Internal Server Error Internal Server Error Error
default Default Unexpected error Error

Response Headers

Status Header Type Format Description
200 BSS-Referral-Token string The UUID that will be included in the boot script. A new UUID is generated on each POST and PUT request.
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

patch__boot_v1_bootparameters

Code samples

PATCH https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X PATCH https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PATCH /boot/v1/bootparameters

Update existing boot parameters

Update an existing entry with new boot parameters while retaining existing settings for the kernel and initrd settings. The entry only needs to specify one or more hosts and the new boot parameters without the need to specify the kernel and initrd entries.

Body parameter

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Parameters

Name In Type Required Description
body body BootParams false none

Example responses

400 Response

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Responses

Status Meaning Description Schema
200 OK Successfully update boot parameters None
400 Bad Request Bad Request - Invalid BootParams value. Error
404 Not Found Does Not Exist - Cannot find entry for specified host, MAC, or NID Error
500 Internal Server Error Internal Server Error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

delete__boot_v1_bootparameters

Code samples

DELETE https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters HTTP/1.1
Host: api-gw-service-nmn.local
Content-Type: application/json
Accept: application/json

# You can also use wget
curl -X DELETE https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api-gw-service-nmn.local/apis/bss/boot/v1/bootparameters", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /boot/v1/bootparameters

Delete existing boot parameters

Remove an existing boot parameter settings for one or more hosts, as specified by hosts, MACs, or NIDs. If you specify a kernel or initrd image, the image entry is removed, and the references by any existing hosts are removed. Note that this can leave a host unbootable, and so will need to be updated with new image references before they will be bootable.

Body parameter

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

Parameters

Name In Type Required Description
body body BootParams false none

Example responses

400 Response

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Responses

Status Meaning Description Schema
200 OK Successfully deleted the appropriate entry or entries None
400 Bad Request Bad Request - Invalid BootParams value. Error
404 Not Found Does Not Exist - Cannot find specified host, MAC, or NID Error
500 Internal Server Error Internal Server Error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

hosts

get__boot_v1_hosts

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/hosts

Retrieve hosts

Retrieve list of known hosts obtained from HSM. This list can be filtered by specifying one or more of the query parameters name=, mac=, and/or nid=. If any of these parameters are specified, then only host information for those items are returned in the response. Multiple hosts can be specified for any of these parameters by specifying a comma-separated list of items, or by providing the query parameter itself more than once. If the same host is referenced more than once, its information will be returned multiple times. In particular, if a host is referenced by both its host name and NID and/or MAC address, this same host information will be returned once for each reference.

Parameters

Name In Type Required Description
name query string false Host name or tag name of boot parameters to return
mac query string false MAC Address of host of boot parameters to return
nid query integer false NID of host of boot parameters to return

Example responses

200 Response

[
  {
    "ID": "x0c0s21b0n0",
    "Type": "Node",
    "State": "Ready",
    "Flag": "OK",
    "Enabled": true,
    "Role": "Compute",
    "RubeRole": "Worker",
    "NID": 2,
    "NetType": "Sling",
    "Arch": "X86",
    "Class": "string",
    "ReservationDisabled": false,
    "Locked": false,
    "FQDN": "string",
    "MAC": [
      "00:40:a6:82:f6:c5",
      "a4:bf:01:3e:c0:a2",
      "00:40:a6:82:f7:0c"
    ],
    "EndpointEnabled": true
  }
]

Responses

Status Meaning Description Schema
200 OK Return list of hosts and associated attributes known to BSS HostInfo
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

post__boot_v1_hosts

Code samples

POST https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X POST https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api-gw-service-nmn.local/apis/bss/boot/v1/hosts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /boot/v1/hosts

Retrieve hosts

Retrieve the latest host information from HSM.

Example responses

400 Response

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Responses

Status Meaning Description Schema
204 No Content Successfully retrieved current state from HSM. None
400 Bad Request Bad Request Error
500 Internal Server Error Internal Server Error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

dumpstate

get__boot_v1_dumpstate

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/dumpstate HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/dumpstate \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/dumpstate', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/dumpstate", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/dumpstate

Retrieve dumpstate

Dump internal state of boot script service for debugging purposes. Return known hosts and associated information, along with the known boot parameter info.

Example responses

200 Response

{
  "components": [
    {
      "schema": {
        "ID": "x0c0s21b0n0",
        "Type": "Node",
        "State": "Ready",
        "Flag": "OK",
        "Enabled": true,
        "Role": "Compute",
        "RubeRole": "Worker",
        "NID": 2,
        "NetType": "Sling",
        "Arch": "X86",
        "Class": "string",
        "ReservationDisabled": false,
        "Locked": false,
        "FQDN": "string",
        "MAC": [
          "00:40:a6:82:f6:c5",
          "a4:bf:01:3e:c0:a2",
          "00:40:a6:82:f7:0c"
        ],
        "EndpointEnabled": true
      }
    }
  ],
  "params": [
    {
      "schema": {
        "hosts": [
          "x0c0s2b0n0",
          "x0c0s3b0n0"
        ],
        "macs": [
          "00:40:a6:82:f6:c5",
          "a4:bf:01:3e:c0:a2",
          "00:40:a6:82:f7:0c"
        ],
        "nids": [
          1,
          2,
          3,
          4
        ],
        "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
        "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
        "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
        "cloud-init": {
          "user-data": {
            "foo": "bar"
          },
          "meta-data": {
            "foo": "bar"
          }
        }
      }
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Return internal service state StateInfo
400 Bad Request Bad Request Error
500 Internal Server Error Internal Server Error Error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

endpoint-history

get__boot_v1_endpoint-history

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/endpoint-history HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/endpoint-history \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/endpoint-history', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/endpoint-history", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/endpoint-history

Retrieve access information for xname and endpoint

Retrieve access information for xname and endpoint. Every time a node requests special types of endpoint (its boot script or cloud-init data) that is recorded in the database. This is useful for determining a number of things most notably as a way to monitor boot progress.

Parameters

Name In Type Required Description
name query string false Xname of the node.
endpoint query string false The endpoint to get the last access information for.

Enumerated Values

Parameter Value
endpoint bootscript
endpoint user-data

Example responses

200 Response

[
  {
    "name": "x3000c0s1b0n0",
    "endpoint": "bootscript",
    "last_epoch": 1635284155
  }
]

Responses

Status Meaning Description Schema
200 OK Endpoint access information Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [EndpointAccess] false none [This data structure is used to return the endpoint access information for a given resource.]
» name string false none Xname of the node
» endpoint string false none none
» last_epoch integer false none Unix epoch time of last request. An epoch of 0 indicates a request has not taken place.

Enumerated Values

Property Value
endpoint bootscript
endpoint user-data
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

service-status

get__boot_v1_service_status

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/service/status

Retrieve the current status of BSS

Retrieve the current status of the BSS service itself.

This endpoint can be used as a liveness probe for the BSS to determine if it is alive or dead.

Example responses

200 Response

{
  "bss-status": "running"
}

Responses

Status Meaning Description Schema
200 OK The BSS REST API is alive and accessible. Inline
500 Internal Server Error Internal Server Error Error

Response Schema

Status Code 200

Name Type Required Restrictions Description
» bss-status string false none Current status of BSS.

Enumerated Values

Property Value
bss-status running
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__boot_v1_service_etcd

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/etcd HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/etcd \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/service/etcd', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/service/etcd", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/service/etcd

Retrieve the current connection status to ETCD

Retrieve the current connection status to the BSS ETCD database.

The connection to ETCD will be tested by writing a value to ETCD, and then reading it back from the database. If the value is successfully writen to ETCD and read back as the same value, then the connection to ETCD is considered to be connected. Otherwise, there is a connection error.

Example responses

200 Response

{
  "bss-status-etcd": "connected"
}

Responses

Status Meaning Description Schema
200 OK The ETCD database connection is healthy. Inline
500 Internal Server Error The ETCD database connection is unhealthy. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» bss-status-etcd string false none Current connection status to ETCD.

Enumerated Values

Property Value
bss-status-etcd connected

Status Code 500

Name Type Required Restrictions Description
» bss-status-etcd string false none Current connection status to ETCD.

Enumerated Values

Property Value
bss-status-etcd error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__boot_v1_service_hsm

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/hsm HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/hsm \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/service/hsm', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/service/hsm", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/service/hsm

Retrieve the current connection status to HSM

Retrieve the current connection status to the Hardware State Manager (HSM).

The connection to HSM will be tested by querying a HSM endpoint to verify HSM is alive.

Example responses

200 Response

{
  "bss-status-hsm": "connected"
}

Responses

Status Meaning Description Schema
200 OK The HSM connection is healthy. Inline
500 Internal Server Error The HSM connection is unhealthy. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» bss-status-hsm string false none Current connection status to HSM.

Enumerated Values

Property Value
bss-status-hsm connected

Status Code 500

Name Type Required Restrictions Description
» bss-status-hsm string false none Current connection status to HSM.

Enumerated Values

Property Value
bss-status-hsm error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__boot_v1_service_version

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/version HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/version \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/service/version', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/service/version", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/service/version

Retrieve the service version

Retrieve the current service version.

Example responses

200 Response

{
  "bss-version": "1.21.0"
}

Responses

Status Meaning Description Schema
200 OK The current running service version. Inline
500 Internal Server Error Internal Server Error. Unable to determine current running service version. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» bss-version string false none none

Status Code 500

Name Type Required Restrictions Description
» bss-version string false none none

Enumerated Values

Property Value
bss-version error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

get__boot_v1_service_status_all

Code samples

GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status/all HTTP/1.1
Host: api-gw-service-nmn.local
Accept: application/json

# You can also use wget
curl -X GET https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status/all \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status/all', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api-gw-service-nmn.local/apis/bss/boot/v1/service/status/all", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /boot/v1/service/status/all

Retrieve the overall service health

Retrieve the overall health of the service, and determine if the service is healthy to serve requests as a readiness probe.

This will retrieve the current BSS version and status, along with the connection status to HSM and ETCD.

Example responses

200 Response

{
  "bss-status": "running",
  "bss-status-etcd": "connected",
  "bss-status-hsm": "connected",
  "bss-version": "1.21.0"
}

Responses

Status Meaning Description Schema
200 OK All service checks reported a healthy status. Inline
500 Internal Server Error One or more service checks reported an unhealthy status. Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» bss-status string false none none
» bss-status-etcd string false none Current connection status to ETCD.
» bss-status-hsm string false none Current connection status to HSM.
» bss-version string false none none

Enumerated Values

Property Value
bss-status running
bss-status-etcd connected
bss-status-hsm connected

Status Code 500

Name Type Required Restrictions Description
» bss-status string false none none
» bss-status-etcd string false none Current connection status to ETCD.
» bss-status-hsm string false none Current connection status to HSM.
» bss-version string false none none

Enumerated Values

Property Value
bss-status running
bss-status-etcd connected
bss-status-etcd error
bss-status-hsm connected
bss-status-hsm error
To perform this operation, you must be authenticated by means of one of the following methods: bearerAuth

Schemas

BootParams

{
  "hosts": [
    "x0c0s2b0n0",
    "x0c0s3b0n0"
  ],
  "macs": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "nids": [
    1,
    2,
    3,
    4
  ],
  "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
  "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
  "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
  "cloud-init": {
    "user-data": {
      "foo": "bar"
    },
    "meta-data": {
      "foo": "bar"
    }
  }
}

When used as a request body, the caller sets boot parameters and specifies hosts, along with the kernel image path/URL and initrd path/URL. To specify hosts, use one of the three parameters - hosts, MACs, or NIDs. If MAC addresses are used, they are mapped to host names based on information retrieved from the hardware state manager. Likewise, if NIDs are used, they are mapped to host names with the same hardware state manager info. While the expected usage is to specify hosts based on their host names, the “macs” and “nids” alternatives may be more convenient in some contexts. You can also specify a general tag for hosts. A tag is ‘Default’, or one of the roles that a node may be defined as in the hardware state manager (HSM). Some of the HSM roles like ‘Compute’, ‘Storage’, ‘System’, and ‘Application’ can be specified as hosts and are managed similar to specific hosts. While BSS allows for fine grained control of individual nodes, the tags are typically more convenient, especially for a large system.

Alternatively, if you specify a kernel or initrd image and params, but no host, MAC, or NID, the boot script service will associate the specified params with the specified kernel or initrd image. When used as a response body, identifies the hosts available for booting using either hosts, MACs, or NIDs, depending on which parameter was used in the request.

Properties

Name Type Required Restrictions Description
hosts [string] false none host names
macs [string] false none MAC addresses
nids [integer] false none Node ID
params string false none Specific to the kernel that is being booted.
kernel string false none URL or file system path specifying kernel image.
initrd string false none URL or file system path specifying initrd image.
cloud-init CloudInit false none Cloud-Init data for the hosts

CloudInit

{
  "user-data": {
    "foo": "bar"
  },
  "meta-data": {
    "foo": "bar"
  }
}

Cloud-Init data for the hosts

Properties

Name Type Required Restrictions Description
meta-data CloudInitMetadata false none Cloud-Init Instance Metadata for a host.
user-data CloudInitUserData false none Cloud-Init User data for a host.
phone-home CloudInitPhoneHome false none Data sent from the Phone Home Cloud-Init module after a host’s boot is complete.

CloudInitMetadata

{}

Cloud-Init Instance Metadata for a host.

Properties

None

CloudInitUserData

{}

Cloud-Init User data for a host.

Properties

None

CloudInitPhoneHome

{
  "pub_key_dsa": "string",
  "pub_key_rsa": "string",
  "pub_key_ecdsa": "string",
  "pub_key_ed25519": "string",
  "instance_id": "string",
  "hostname": "string",
  "fqdn": "string"
}

Data sent from the Phone Home Cloud-Init module after a host’s boot is complete.

Properties

Name Type Required Restrictions Description
pub_key_dsa string false none none
pub_key_rsa string false none none
pub_key_ecdsa string false none none
pub_key_ed25519 string false none none
instance_id string false none none
hostname string false none none
fqdn string false none none

Component

{
  "ID": "x0c0s21b0n0",
  "Type": "Node",
  "State": "Ready",
  "Flag": "OK",
  "Enabled": true,
  "Role": "Compute",
  "RubeRole": "Worker",
  "NID": 2,
  "NetType": "Sling",
  "Arch": "X86",
  "Class": "string",
  "ReservationDisabled": false,
  "Locked": false,
  "FQDN": "string",
  "MAC": [
    "00:40:a6:82:f6:c5",
    "a4:bf:01:3e:c0:a2",
    "00:40:a6:82:f7:0c"
  ],
  "EndpointEnabled": true
}

This data structure is used to return host info for debug purposes

Properties

Name Type Required Restrictions Description
ID string false none none
Type string false none none
State string false none none
Flag string false none none
Enabled boolean false none none
Role string false none none
RubeRole string false none none
NID integer false none none
NetType string false none none
Arch string false none none
Class string false none none
ReservationDisabled boolean false none none
Locked boolean false none none
FQDN string false none none
MAC [string] false none none
EndpointEnabled boolean false none none

StateInfo

{
  "components": [
    {
      "schema": {
        "ID": "x0c0s21b0n0",
        "Type": "Node",
        "State": "Ready",
        "Flag": "OK",
        "Enabled": true,
        "Role": "Compute",
        "RubeRole": "Worker",
        "NID": 2,
        "NetType": "Sling",
        "Arch": "X86",
        "Class": "string",
        "ReservationDisabled": false,
        "Locked": false,
        "FQDN": "string",
        "MAC": [
          "00:40:a6:82:f6:c5",
          "a4:bf:01:3e:c0:a2",
          "00:40:a6:82:f7:0c"
        ],
        "EndpointEnabled": true
      }
    }
  ],
  "params": [
    {
      "schema": {
        "hosts": [
          "x0c0s2b0n0",
          "x0c0s3b0n0"
        ],
        "macs": [
          "00:40:a6:82:f6:c5",
          "a4:bf:01:3e:c0:a2",
          "00:40:a6:82:f7:0c"
        ],
        "nids": [
          1,
          2,
          3,
          4
        ],
        "params": "console=tty0 console=ttyS0,115200n8 initrd=initrd-4.12.14-15.5_8.1.96-cray_shasta_c root=crayfs nfsserver=10.2.0.1nfspath=/var/opt/cray/boot_images imagename=/SLES selinux=0 rd.shell rd.net.timeout.carrier=40 rd.retry=40 ip=dhcp rd.neednet=1 crashkernel=256M htburl=https://api-gw-service-nmn.local/apis/hbtd/hmi/v1/heartbeat bad_page=panic hugepagelist=2m-2g intel_iommu=off iommu=pt numa_interleave_omit=headless numa_zonelist_order=node oops=panic pageblock_order=14 pcie_ports=native printk.synchronous=y quiet turbo_boost_limit=999",
        "kernel": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/kernel",
        "initrd": "s3://boot-images/1dbb777c-2527-449b-bd6d-fb4d1cb79e88/initrd",
        "cloud-init": {
          "user-data": {
            "foo": "bar"
          },
          "meta-data": {
            "foo": "bar"
          }
        }
      }
    }
  ]
}

This data structure is used to return the full component and boot parameter info of the dumpstate request.

Properties

Name Type Required Restrictions Description
components [object] false none none
» schema Component false none This data structure is used to return host info for debug purposes
params [object] false none none
» schema BootParams false none When used as a request body, the caller sets boot parameters and specifies hosts, along with the kernel image path/URL and initrd path/URL. To specify hosts, use one of the three parameters - hosts, MACs, or NIDs. If MAC addresses are used, they are mapped to host names based on information retrieved from the hardware state manager. Likewise, if NIDs are used, they are mapped to host names with the same hardware state manager info. While the expected usage is to specify hosts based on their host names, the “macs” and “nids” alternatives may be more convenient in some contexts.
You can also specify a general tag for hosts. A tag is ‘Default’, or one of the roles that a node may be defined as in the hardware state manager (HSM). Some of the HSM roles like ‘Compute’, ‘Storage’, ‘System’, and ‘Application’ can be specified as hosts and are managed similar to specific hosts. While BSS allows for fine grained control of individual nodes, the tags are typically more convenient, especially for a large system.

Alternatively, if you specify a kernel or initrd image and params, but no host, MAC, or NID, the boot script service will associate the specified params with the specified kernel or initrd image. When used as a response body, identifies the hosts available for booting using either hosts, MACs, or NIDs, depending on which parameter was used in the request.

HostInfo

[
  {
    "ID": "x0c0s21b0n0",
    "Type": "Node",
    "State": "Ready",
    "Flag": "OK",
    "Enabled": true,
    "Role": "Compute",
    "RubeRole": "Worker",
    "NID": 2,
    "NetType": "Sling",
    "Arch": "X86",
    "Class": "string",
    "ReservationDisabled": false,
    "Locked": false,
    "FQDN": "string",
    "MAC": [
      "00:40:a6:82:f6:c5",
      "a4:bf:01:3e:c0:a2",
      "00:40:a6:82:f7:0c"
    ],
    "EndpointEnabled": true
  }
]

This data structure is used to return the component info for a /hosts get request

Properties

Name Type Required Restrictions Description
anonymous [Component] false none This data structure is used to return the component info for a /hosts get request

EndpointAccess

{
  "name": "x3000c0s1b0n0",
  "endpoint": "bootscript",
  "last_epoch": 1635284155
}

This data structure is used to return the endpoint access information for a given resource.

Properties

Name Type Required Restrictions Description
name string false none Xname of the node
endpoint string false none none
last_epoch integer false none Unix epoch time of last request. An epoch of 0 indicates a request has not taken place.

Enumerated Values

Property Value
endpoint bootscript
endpoint user-data

Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Return an RFC7808 error response.

Properties

Name Type Required Restrictions Description
type string false none none
title string false none none
status integer false none none
detail string false none none
instance string false none none