diff --git a/.github/workflows/commit-changes.sh b/.github/workflows/commit-changes.sh new file mode 100755 index 00000000..4382d4d9 --- /dev/null +++ b/.github/workflows/commit-changes.sh @@ -0,0 +1,43 @@ +#!/bin/bash -x +# (C) Copyright 2022 Hewlett Packard Enterprise Development LP +# + +set -eu + +WATCH_DIR=${WATCH_DIR:-.} + +if [[ -n `git status -s ${WATCH_DIR}` ]] +then + git add ${WATCH_DIR} + git commit -m "${GIT_COMMIT_MESSAGE:-commit changes}" +else + echo "${WATCH_DIR} is already up-to-date" + exit 0 +fi + +REMOTE="${REMOTE:-https://x-access-token:${GITHUB_TOKEN}@github.com/${REPOSITORY}}" + +MAX_RETRIES=${MAX_RETRIES:-3} +ATTEMPT=0 +while true +do + if git push "${REMOTE}" + then + break + fi + + ATTEMPT=$((ATTEMPT + 1)) + if [[ ${ATTEMPT} -ge ${MAX_RETRIES} ]] + then + echo "Failed to successfully sync with remote after ${MAX_RETRIES} attempts" + exit 1 + fi + + echo "Try ${ATTEMPT}: failed to push, waiting 2 seconds before fetching latest and retrying..." + + sleep 2 + + git pull --rebase "${REMOTE}" +done + +echo "Successfully pushed latest changes to remote" \ No newline at end of file diff --git a/.github/workflows/html.yml b/.github/workflows/html.yml new file mode 100644 index 00000000..fe85de62 --- /dev/null +++ b/.github/workflows/html.yml @@ -0,0 +1,46 @@ +#(C) Copyright 2022 Hewlett Packard Enterprise Development LP + +name: HTML Doc + +on: + push: + branches: + - master + +jobs: + ci: + runs-on: ubuntu-20.04 + steps: + - name: Checkout workspace + uses: actions/checkout@v3 + + - name: Set up Node.js + uses: actions/setup-node@v3 + with: + node-version: 16.13.2 + + - name: Install dependencies + run: | + # redocly CLI + npm i -g redoc-cli + # yq + wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O yq + chmod +x yq + export PATH=${PATH}:`pwd` + + - name: Generate HTML doc + run: (cd v1 && make gen-html) + + - name: Commit changes + run: .github/workflows/commit-changes.sh + env: + WATCH_DIR: "v1/html" + GIT_AUTHOR_NAME: ${{ github.actor }} + GIT_AUTHOR_EMAIL: ${{ github.actor }}@users.noreply.github.com + GIT_COMMITTER_NAME: GitHub Actions + GIT_COMMITTER_EMAIL: actions@github.com + GIT_COMMIT_MESSAGE: | + [dependabot skip] Sync changes with gen-html + BRANCH_REF: ${{ github.event.pull_request.head.ref }} + REPOSITORY: ${{ github.repository }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/build/html_generate.sh b/build/html_generate.sh index 9e4cda8d..a3491535 100644 --- a/build/html_generate.sh +++ b/build/html_generate.sh @@ -11,11 +11,16 @@ set -euo pipefail -if [ $# -ne 1 ]; then - echo "usage: $0 " 1>&2 +if [ $# -lt 1 ]; then + echo "usage: $0 []" 1>&2 exit 1 fi +OUTPUT_FILE="index.html" +if [[ ! -z "$2" ]]; then + OUTPUT_FILE="${2}" +fi + API_FILE=$1 TEMP_DIR=$(mktemp -d) @@ -37,4 +42,4 @@ yq -i '.info.description={"$ref": "./html/docs/api_description.md"}' ${TEMP_MAIN yq -i '.externalDocs={"description":"API Versioning", "url":"https://www.hpe.com/us/en/software/licensing.html"}' ${TEMP_MAIN_FILE} # generate HTML file. -redoc-cli build -o ./html/GLPCE_BMaaS_API_Spec.html ${TEMP_MAIN_FILE} +redoc-cli build -o ${OUTPUT_FILE} ${TEMP_MAIN_FILE} diff --git a/v1/Makefile b/v1/Makefile index d1dcb951..1729c447 100644 --- a/v1/Makefile +++ b/v1/Makefile @@ -59,4 +59,5 @@ fixup: api_files vendor .PHONY: gen-html gen-html: - @(cd ../build; bash html_generate.sh ${PWD}/api/swagger/swagger.yaml) + (cd ../build; \ + bash -x html_generate.sh ${PWD}/api/swagger/swagger.yaml ${PWD}/html/index.html) diff --git a/v1/html/index.html b/v1/html/index.html new file mode 100644 index 00000000..bfb11b4b --- /dev/null +++ b/v1/html/index.html @@ -0,0 +1,2919 @@ + + + + + + HPE GreenLake for bare metal API + + + + + + + + + +
API docs by Redocly

HPE GreenLake for bare metal API (v1)

Download OpenAPI specification:Download

License: HPE End User License Agreement
API Versioning

Introduction

Welcome to HPE GreenLake for bare metal APIs.

+

The HPE GreenLake for bare metal is included as part of the HPE GreenLake for Private Cloud +Enterprise service, and it is sometimes also called Bare Metal as a Service or BMaaS.

+

This document describes the HPE GreenLake for bare metal APIs protocol and available endpoints.

+

The BMaaS API is built on HTTP and is RESTful. It has predictable resource URLs. It returns HTTP +response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can +use your favorite HTTP/REST library for your programming language to use HPE GreenLake for Private +Cloud Enterprise bare metal APIs.

+

The APIs provides access to bare metal service within a single project context. Clients can create +fully-provisioned hosts, storage volumes, and project-specific private networks in an isolated +project environment. Clients can also access information about available services and resources +through the available-resources API. This API provides detailed information about OS imaging options, +machine size options, storage volume options, and data center locations which are needed when creating +hosts and volumes.

+

The API specification references a few resources by the deprecated name, which differs from the name +displayed in HPE GreenLake Central UI. The table below maps the resource's old name in the API +specification with the corresponding name in HPE GreenLake Central UI.

+ + + + + + + + + + + + + + + + + + + + + + + +
SNName in API SpecName in GreenLake Central
1ProjectCompute Group
2HostCompute Instance
3Machine SizeCompute Instance Type
+

Authentication

Bearer Auth

The HPE GreenLake for bare metal APIs use Bearer Authentication that requires the users to provide +a bearer token in the Authorization header. The service supports two types of tokens, the HPE +GreenLake IAM token and the Metal classic token. The Metal classic token is for HPE internal use only. +The clients are required to provide HPE GreenLake IAM token to authenticate with the HPE GreenLake +for bare metal APIs. The access token can be obtained using any of the following ways.

+

Option 1: API client(recommended)

+ +

An API client allows nonhuman entities (an application service account, for instance) programmatic access to a resource on a space.

+ +

Note: Make sure to save the Issuer Url, Client ID, and Client Secret

+ +

Note: Make sure to assign the appropriate HPE GreenLake for bare metal user roles in HPE GreenLake Central.

+
    +
    • +
    1. Make a REST call to generate the API access token:
      2. +
    +
    • +
+
curl -i -X POST \
+  '{issuerUrl}/v1/token' \
+  -H 'Content-Type: application/x-www-form-urlencoded' \
+  -d 'client_id={clientID}' \
+  -d 'client_secret={clientSecret}' \
+  -d grant_type=client_credentials \
+  -d scope=hpe-tenant
+
+

Obtain the access_token from the response.

+

Option 2: Getting the token directly from UI

+ +

To authenticate with the BMaaS API you need to obtain the access token from + + HPE GreenLake Central + +. +Once logged in to HPE GreenLake Central, +Click the + +icon in the top right corner and then click + +. In the API Access page, click the + +icon to copy the personal access token.

+
+ +

INFO +For both the options, the access token lease expires in 15 minutes.

+

Project API Key

The specific Project ID must be provided with Project header when accessing service within a single project context. +Used only when using HPE GreenLake IAM issued access tokens.

+

Membership API Key

HPE Internal use only. Required only when using classic Metal access tokens.

+

Getting a Space name or ID

Space name or ID is required in header for a few Project level APIs. You can obtain the Space name and the corresponding ID from + + HPE GreenLake Central + +.
Once logged in to HPE GreenLake Central, +Click the + +icon in the top right corner and copy the value of Space field.

+

The corresponding ID for the Space can be extracted from the current URL in the address bar.
It is the value of spaceid query parameter at the end of a URL after a '?' symbol.

+

HPE GreenLake for bare metal APIs

version

Read-only operation to get api server build version information.

+

Get api server build version

Authorizations:
(BearerAuthMembership) BearerAuth

Responses

Response samples

Content type
application/json
{
  • "Build": "0.8.6-dev-218-g0b3b1ad"
}

projects

Operations related to Projects. A Project defines an isolated space for creating Hosts, Volumes, and private Networks. A project is a.k.a. Compute Group.

+

List of all Projects within an organization or cluster

Returns an array of all Project objects that have been created. This includes profile information for the project and project limits on resouces like hosts, private networks, volumes, and volume capacity. If GreenLake IAM issued token is used for authentication, then it is required to pass either 'Space' or 'spaceid' header. When both are set, 'Space' header is ignored.

+
Authorizations:
(BearerAuthMembership) BearerAuth
header Parameters
spaceid
string
Example: 95688cf9-82ff-4e32-80fc-2b0b41648dab

GreenLake space ID

+
Space
string
Example: Default

GreenLake space name

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new project

Adds a new Project which creates an isolated space for creating Hosts, Volumes, and private Networks. A project is often aligned to a specific team within an organization or a cluster. If GreenLake IAM issued token is used for authentication, then it is required to pass either 'Space' or 'spaceid' header. When both are set, 'Space' header is ignored. Note that Hoster or BMaaS Access Owner role is required for this operation.

+
Authorizations:
(BearerAuthMembership) BearerAuth
header Parameters
Space
string
Example: Default

GreenLake space name

+
spaceid
string
Example: 95688cf9-82ff-4e32-80fc-2b0b41648dab

GreenLake space ID

+
Request Body schema: application/json

NewProject parameters to create a new Project

+
Name
required
string
required
object (Profile)
required
object (Limits)
PermittedSites
Array of strings <uuid>

Array listing the permitted site IDs

+

Responses

Request samples

Content type
application/json
{
  • "Name": "Project foobar",
  • "Profile": {
    },
  • "Limits": {
    },
  • "PermittedSites": [
    ]
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Profile": {
    },
  • "Limits": {
    },
  • "Resources": {
    },
  • "PermittedSites": [
    ]
}

Retrieve a project by its ID

Returns a single Project object with its matching ID This includes profile information for the project and project limits on resouces like hosts, private networks, volumes, and volume capacity.

+
Authorizations:
(BearerAuthMembership) BearerAuth
path Parameters
projectId
required
string

ID of project to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Profile": {
    },
  • "Limits": {
    },
  • "Resources": {
    },
  • "PermittedSites": [
    ]
}

Update a project by its ID

Updates a project with a matching ID. Only Project 'Name', 'Profile' and 'Limits' can be updated with this operation. Note that Hoster or BMaaS Access Owner role is required for this operation.

+
Authorizations:
(BearerAuthMembership) BearerAuth
path Parameters
projectId
required
string

ID of project to update

+
Request Body schema: application/json

Project parameters to update an existing Project

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
required
object (Profile)
required
object (Limits)
object (ProjectResources)
PermittedSites
Array of strings <uuid>

Array listing the permitted site IDs

+

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Profile": {
    },
  • "Limits": {
    },
  • "Resources": {
    },
  • "PermittedSites": [
    ]
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Profile": {
    },
  • "Limits": {
    },
  • "Resources": {
    },
  • "PermittedSites": [
    ]
}

Delete a Project

Deletes the Project with the matching ID. Note that Hoster or BMaaS Access Owner role is required for this operation.

+
Authorizations:
(BearerAuthMembership) BearerAuth
path Parameters
projectId
required
string

ID of project to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

sshkeys

Operations related to SSH Keys. Clients may define SSH Keys that can then be referenced by ID when creating a Host.

+

List all sshkeys in project

Returns an array of all SSHKey objects defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new SSH Key

Adds a new SSH Key that can be referenced when creating a Host

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

SSH Key that is to be added to the project

+
Name
required
string
Key
required
string (SSHKeyValue)

SSH key value

+

Responses

Request samples

Content type
application/json
{
  • "Name": "Joe's Laptop",
  • "Key": "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxv1C5uOeG9BBjfQbum9GupGthTFcifS4FNYxZ2ZakN9UcpD05L2lKp4OI6mfCfciOhJ9SHduZWJFM0pYfC99hIsPAHhEwWOjh3/rHKxB/U4RYN4VFWM+ShDv92+k0Hse73HhuiHKVtmRj/fltAeCFm/mPlL+McMYFhFYMIK8b/spKpXxdEBCSowHPGIn3yi0ivPWhC4wcIa9jDIela/a0t/oDnYTeIp2WMLDbpZyQsGHmKopAAvb+83JhwytQMVTI/g5pMerbqPyxKtWaWDVDtpQ7O8G877T5U3kkl4jLLOJywxrvLrfHh1UNdNvPmvRFd+ct9Q5ugj5CIMJHqWTj Joe@Laptop.local'\n"
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Key": "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxv1C5uOeG9BBjfQbum9GupGthTFcifS4FNYxZ2ZakN9UcpD05L2lKp4OI6mfCfciOhJ9SHduZWJFM0pYfC99hIsPAHhEwWOjh3/rHKxB/U4RYN4VFWM+ShDv92+k0Hse73HhuiHKVtmRj/fltAeCFm/mPlL+McMYFhFYMIK8b/spKpXxdEBCSowHPGIn3yi0ivPWhC4wcIa9jDIela/a0t/oDnYTeIp2WMLDbpZyQsGHmKopAAvb+83JhwytQMVTI/g5pMerbqPyxKtWaWDVDtpQ7O8G877T5U3kkl4jLLOJywxrvLrfHh1UNdNvPmvRFd+ct9Q5ugj5CIMJHqWTj Joe@Laptop.local'\n"
}

Retrieve SSH Key by ID

Returns a single SSH key with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
sshkeyId
required
string

ID of sshkey to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Key": "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxv1C5uOeG9BBjfQbum9GupGthTFcifS4FNYxZ2ZakN9UcpD05L2lKp4OI6mfCfciOhJ9SHduZWJFM0pYfC99hIsPAHhEwWOjh3/rHKxB/U4RYN4VFWM+ShDv92+k0Hse73HhuiHKVtmRj/fltAeCFm/mPlL+McMYFhFYMIK8b/spKpXxdEBCSowHPGIn3yi0ivPWhC4wcIa9jDIela/a0t/oDnYTeIp2WMLDbpZyQsGHmKopAAvb+83JhwytQMVTI/g5pMerbqPyxKtWaWDVDtpQ7O8G877T5U3kkl4jLLOJywxrvLrfHh1UNdNvPmvRFd+ct9Q5ugj5CIMJHqWTj Joe@Laptop.local'\n"
}

Update an existing SSH Key. Only 'Name' or 'Key' fields can be changed.

Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
sshkeyId
required
string

ID of sshkey to update

+
Request Body schema: application/json

Updated SSH key

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
Key
required
string (SSHKeyValue)

SSH key value

+

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Key": "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxv1C5uOeG9BBjfQbum9GupGthTFcifS4FNYxZ2ZakN9UcpD05L2lKp4OI6mfCfciOhJ9SHduZWJFM0pYfC99hIsPAHhEwWOjh3/rHKxB/U4RYN4VFWM+ShDv92+k0Hse73HhuiHKVtmRj/fltAeCFm/mPlL+McMYFhFYMIK8b/spKpXxdEBCSowHPGIn3yi0ivPWhC4wcIa9jDIela/a0t/oDnYTeIp2WMLDbpZyQsGHmKopAAvb+83JhwytQMVTI/g5pMerbqPyxKtWaWDVDtpQ7O8G877T5U3kkl4jLLOJywxrvLrfHh1UNdNvPmvRFd+ct9Q5ugj5CIMJHqWTj Joe@Laptop.local'\n"
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Key": "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCxv1C5uOeG9BBjfQbum9GupGthTFcifS4FNYxZ2ZakN9UcpD05L2lKp4OI6mfCfciOhJ9SHduZWJFM0pYfC99hIsPAHhEwWOjh3/rHKxB/U4RYN4VFWM+ShDv92+k0Hse73HhuiHKVtmRj/fltAeCFm/mPlL+McMYFhFYMIK8b/spKpXxdEBCSowHPGIn3yi0ivPWhC4wcIa9jDIela/a0t/oDnYTeIp2WMLDbpZyQsGHmKopAAvb+83JhwytQMVTI/g5pMerbqPyxKtWaWDVDtpQ7O8G877T5U3kkl4jLLOJywxrvLrfHh1UNdNvPmvRFd+ct9Q5ugj5CIMJHqWTj Joe@Laptop.local'\n"
}

Delete an SSH key

Deletes the SSH key with the matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
sshkeyId
required
string

ID of sshkey to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

hosts

Operations related to Hosts. A host is a fully-provisioned physical server. Clients may create, view, list, and delete hosts. A host is a.k.a. Compute Instance.

+

List all Hosts in project

Returns an array of all Host objects defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
query Parameters
all
string
Value: "true"

Includes deleted Host objects in the response when set to "true".

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Host

Creates a new host object which kicks off the provisioning of a physical server in accordance to the attributes provided for the Host object. Most values for these options must be selected from the set of options provided by the get available-resources API call. +The SvcFlavor, SvcVersion, LocationID, SSHKeyIDs, and Network attribute must all be set with appropriate ID values from the available-resources call.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

Defines the configuration of the desired host. See the schema for descriptions of individual attributes.

+
Name
required
string

The host name used when installing the host operating system. Note that some OS implementations may require the name to be formatted as a fully qualified domain name.

+
Description
string
ServiceID
required
string <uuid>

The image service identifier must be identifer of one of the available imaging services provided by the AvailableImage array returned as part of the get /available-resources call. Images are typically described by category (e.g. Linux), flavor (e.g. ubuntu) and version (e.g. 18.04-20190807)

+
LocationID
required
string <uuid>

The location ID must be one of those provided by the LocationInfo array returned as part of the get /available-resources call. The locations are typically described by country, region, and data center. +The location ID must also be one that has sufficient inventory for the selected MachineSize. See the MachineInventory array as returned by the get /available-resources call to select a location that has machines available with the correct machine size.

+
MachineSizeID
required
string <uuid>

The machine size ID must be one of those listed in the MachineSizes array returned as part of the get /available-resources call. This array provides the name and detailed description for each machine size. Use the MachineInventory array provided by the get /available-resources call to find a location with an adequate inventory of machines with the desired machine size.

+
MachineID
string <uuid>

The machine ID is normally not used.

+
SSHKeyIDs
required
Array of strings <uuid>

These IDs must correspond to the IDs for SSH keys already created within the context of the project. These SSH keys and those included as SSHAuthorizedKeys will be used together to provision SSH keys when the machine is imaged.

+
NetworkIDs
required
Array of strings <uuid>

The list of IDs corresponding to the networks that will be provisioned to the host. These networks must be among those listed in the Networks array returned by the get /available-resources call. This list must include the ID for any network identified by the HostUseEnum as Required.

+
PreAllocatedIPs
Array of strings

A list of pre-allocated IP addresses to be used for corresponding networks. This array of IP addresses, if present, is in one-to-one correspondence with Networks.

+
NetworkForDefaultRoute
required
string <uuid>

The host's default network ID. This needs to be one of the values in the "NetworkIDs" list.

+
NetworkUntagged
string <uuid>

ID of the network selected to be untagged. This needs to be one of the values in the "NetworkIDs" list.

+
VolumeIDs
Array of strings <uuid>

The list of IDs corresponding to existing, unattached volumes that should be attached to the new host. The volume must be one of those listed in the Volumes array returned by the get /available-resources call. In addition, the volume must be in the visible state and not a part of any current VolumeAttachment (see get volume-attachments)

+
object

The map of Service Network (Provider) ID to Provider MAC address. The Service Network must be a provider network provisioned to this host. Any Service Networks not included here will default to the physical MAC learned during machine discovery.

+
Array of objects (AddVolume)

New volumes may be created and connected to the Host when the host is provisioned. The information provided here to create a host is the same as required when doing a post /volumes call

+
UserData
string

User-provided data to be attached to the image configuration data.

+
NodeID
string

User-provided data to represent the identity of the host within an application environment. For example, this could be set to represent the Kubernetes node ID if the host is provisioned as a Kubernetes node.

+
object

The map of label name to label value for this host.

+

Responses

Request samples

Content type
application/json
{
  • "Name": "NewHostName",
  • "Description": "Description of new Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "NetworkIDs": [
    ],
  • "PreAllocatedIPs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "VolumeIDs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "NewVolumes": [
    ],
  • "UserData": "string",
  • "NodeID": "Node21",
  • "Labels": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Retrieve Host by ID

Returns a single Host with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Update an existing Host

Updates the Host with the matching ID. Update is permitted only if the host is in the 'Ready' or 'Connection Updating Failed' state. Only the Host 'Description', 'Networks', 'NetworkForDefaultRoute', 'NetworkUntagged' and 'ISCSIConfig:InitiatorName' can be updated. 'ISCSIConfig:InitiatorName' can be updated only if the host has no volumes attached.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of host to update

+
Request Body schema: application/json

Updated Host

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
Description
required
string
ServiceID
string <uuid>

The image service identifier used to image the server. ServiceID is one of those listed by the Images array returned as part of the get /available-resources call.

+
ServiceFlavor
string

Overall flavor of server image used to image the server

+
ServiceVersion
string

Version of the ServiceFlavor used to image the server

+
LocationID
string <uuid>

The location of the machine assigned to the host. LocationID is one of those listed by the LocationInfo array returned as part of the get /available-resources call.

+
MachineSizeName
string

Name of the machine size used to identify and select the machine assigned to the host. MachineSizes are described by the MachineSize array returned by the get /available-resources call.

+
MachineSizeID
string <uuid>

UniqueID referring to the machine size used to identify and select the machine assigned to the host. MachineSizes are described by the MachineSize array returned by the get /available-resources call.

+
MachineID
string <uuid>

UniqueID referring to the machine on which this host is running.

+
SSHKeyIDs
Array of strings <uuid>

IDs of SSH Keys used when configuring the Host

+
SSHAuthorizedKeys
Array of strings (SSHKeyValue)

Specific SSH keys that were when configuring the host.

+
NetworkIDs
required
Array of strings <uuid>

The list of IDs corresponding to the networks that were provisioned to the host. These networks are among those listed in the Networks array returned by the get /available-resources call.

+
NetworkForDefaultRoute
required
string <uuid>

The host's default network ID. This needs to be one of the values in the "NetworkIDs" list.

+
NetworkUntagged
required
string <uuid>

ID of the network selected to be untagged. This needs to be one of the values in the "NetworkIDs" list.

+
PreAllocatedIPs
Array of strings

The list of pre-allocated IP addresses corresponding to the list of NetworkIDs. Pre-allocated IP addresses are optional, but required when updating a host containing Pre-allocated IP addresses.

+
object

The map of Service Network (Provider) ID to Provider MAC address. The Service Network must be a provider network provisioned to this host. Any Service Networks not included here will default to the physical MAC learned during machine discovery.

+
UserData
string

User-provided data attached to the image configuration data when the host was provisioned

+
NodeID
string

User-provided data to represent the identity of the host within an application environment. For example, this could be set to represent the Kubernetes node ID if the host is provisioned as a Kubernetes node.

+
object or null (HostISCSIConfig)
Array of objects (HostConnection)

Details describing host network connections

+
Deleted
boolean

True if the Host has been deleted.

+
PortalCommOkay
boolean

Describes if the portal is in active communication to the device

+
PowerStatus
string (HostPowerState)
Enum: "ON" "OFF" "UNKNOWN"

Current power status of the underlaying physical server (machine)

+
State
string (HostState)
Enum: "New" "Deleting" "Deleted" "Failed" "Updating Connections" "Imaging" "Connecting" "Booting" "Ready" "Replacing" "Releasing" "Allocating" "Maintenance"

Overall host state

+
Substate
string (HostSubstate)
Enum: "" "Abort Deploy" "Allocate" "Attach Volumes" "Boot Service-OS" "Clear Log" "Complete" "Confirm Off" "Confirm On" "Connect" "Connect Provisioning" "Deploy" "Detach Volumes" "Error Recovery" "Fail Cleanup" "Failed" "Init" "Init Off" "Isolate" "In Maintenance" "Power Off" "Power On" "Release" "Release With Problem" "Set Boot Disk" "Snap Log" "Update"

Host substate within HostState

+
StateTime
string <date-time>
SubstateTime
string <date-time>
Progress
integer <int64> [ 0 .. 100 ]
Alert
boolean
Array of objects (HostAlertInfo)
Workflow
string

The current workflow the host is in

+
SummaryStatus
string (HealthStatus)
Enum: "OK" "Warning" "Critical" "Unknown"
object

The map of label name to label value for the host.

+

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Delete a Host

Deletes the Host with the matching ID. A host in the 'Ready' state must first be powered-off before a delete will be permitted. Deletes to hosts in other states is permitted regardless of the power state

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

Do maintenance on a Host by ID

Do maintenance on a host by executing pre-defined operations. The host must be powered off. The host must also be in the Ready state or in the Failed state and in the Maintenance workflow.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to do maintenance on

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Power on Host by ID

Powers on a single Host with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to power on

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Power off Host by ID

Powers off a single Host with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to power off

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Reset Host by ID

Resets a single Host with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to reset

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Set PXE boot order on Host by ID

Sets a single Host with matching ID to attempt PXE boot when next booting

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to set to PXE boot

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Set HDD boot order on Host by ID

Sets a single Host with matching ID to attempt HDD boot

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to set to HDD boot

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

Replace Host by ID

Re-deploys a host with a new machine that satisfies the current host settings. Only the machine is replaced, IP addresses, volumes, etc are not changed. The host must be powered off. The host must also be in the Ready state or in the Failed state and in the Replace or Maintenace workflow.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
hostId
required
string

ID of Host to replace

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of Host",
  • "ServiceID": "20dd558b-b106-40bc-a8e7-d364ec5db710",
  • "ServiceFlavor": "ubuntu",
  • "ServiceVersion": "18.04-20190807",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "MachineSizeName": "HPE Large",
  • "MachineSizeID": "6e87f64f-b099-4286-9101-bee60a1afa2e",
  • "MachineID": "d96dbf89-2a07-42f9-817d-2d6c42351827",
  • "SSHKeyIDs": [
    ],
  • "SSHAuthorizedKeys": [
    ],
  • "NetworkIDs": [
    ],
  • "NetworkForDefaultRoute": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  • "NetworkUntagged": "046b6c7f-0b8a-43b9-b35d-6489e6daee92",
  • "PreAllocatedIPs": [
    ],
  • "ServiceNetsProviderMAC": {
    },
  • "UserData": "string",
  • "NodeID": "Node21",
  • "ISCSIConfig": {
    },
  • "Connections": [
    ],
  • "Deleted": true,
  • "PortalCommOkay": true,
  • "PowerStatus": "ON",
  • "State": "Ready",
  • "Substate": "Complete",
  • "StateTime": "2019-08-24T14:15:22Z",
  • "SubstateTime": "2019-08-24T14:15:22Z",
  • "Progress": 100,
  • "Alert": true,
  • "AlertInfo": [
    ],
  • "Workflow": "string",
  • "SummaryStatus": "OK",
  • "Labels": {
    }
}

volumes

Operations related to Volumes. A Volume is an external storage volume that persists independent of the associated host.

+

List all volumes in project

Returns an array of all volumes defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new volume

Adds a new volume to the project. Volumes may be created separately and then referenced in the create Host call; or volumes may be created directly within the create Host call.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

Volume that is to be added to the project

+
Name
required
string
Description
string
FlavorID
required
string <uuid>

Adds a new volume to the project. This object requires the LocationID and is used when a new volume is created independently from the host creation therefore requiring a specified location.

+
Capacity
required
integer <int64> >= 0

The size of the volume in GiB

+
Shareable
boolean

Indicates if the volume can be attached to multiple hosts

+
LocationID
required
string <uuid>

The location of the volume (and the storage array) LocationID is one of those listed by the LocationInfo array returned as part of the get /available-resources call. Any volumes must be in the same location as their attached Host.

+
object

The map of label name to label value for this volume.

+

Responses

Request samples

Content type
application/json
{
  • "Name": "NewVolumeName",
  • "Description": "Description of New Volume",
  • "FlavorID": "69d82b9f-19a6-47cd-bcb3-7f4b437e8e51",
  • "Capacity": 10,
  • "Shareable": true,
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Labels": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of New Volume",
  • "FlavorID": "69d82b9f-19a6-47cd-bcb3-7f4b437e8e51",
  • "Capacity": 10485760,
  • "Shareable": true,
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "State": "new",
  • "SubState": "idle",
  • "Status": "ok",
  • "Labels": {
    },
  • "WWN": "string"
}

Retrieve volume by ID

Returns a single volume with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
volumeId
required
string

ID of volume to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of New Volume",
  • "FlavorID": "69d82b9f-19a6-47cd-bcb3-7f4b437e8e51",
  • "Capacity": 10485760,
  • "Shareable": true,
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "State": "new",
  • "SubState": "idle",
  • "Status": "ok",
  • "Labels": {
    },
  • "WWN": "string"
}

Update an existing volume

Updates volume with matching ID. Update is permitted only when volume is in 'Allocated' or 'Visible' state. Only the Volume 'Capacity' can be updated with a value greater than the existing one to expand the volume.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

Volume object with its ID and Capacity in GiB indicating the expanded size to be specified.

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
Description
string
FlavorID
string <uuid>

The VolumeFlavorID matching an entry in the VolumeFlavors array returned as part of the get /available-resources call

+
Capacity
integer <int64> >= 0

The size of the volume in KiB

+
Shareable
boolean

Indicates if the volume can be attached to multiple hosts

+
LocationID
string <uuid>

The location of the volume (and the storage array) LocationID is one of those listed by the LocationInfo array returned as part of the get /available-resources call. Any volumes must be in the same location as their attached Host.

+
State
string (VolumeState)
Enum: "new" "allocating" "allocated" "visible" "deleting" "deleted" "failed"

Current volume state expressed as a string enum value (new, allocating, allocated, visible, deleting, deleted, failed)

+
SubState
string (VolumeSubState)
Enum: "idle" "update-requested" "updating"

Current update state of volume expressed as a string enum value (idle, update-requested, updating)

+
Status
string (VolumeStatus)
Enum: "ok" "error" "degraded"

Current volume status expressed as a string enum values (ok, error, degraded)

+
object

The map of label name to label value for the volume.

+
WWN
string

Serial number of the volume.

+

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of New Volume",
  • "FlavorID": "69d82b9f-19a6-47cd-bcb3-7f4b437e8e51",
  • "Capacity": 10485760,
  • "Shareable": true,
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "State": "new",
  • "SubState": "idle",
  • "Status": "ok",
  • "Labels": {
    },
  • "WWN": "string"
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of New Volume",
  • "FlavorID": "69d82b9f-19a6-47cd-bcb3-7f4b437e8e51",
  • "Capacity": 10485760,
  • "Shareable": true,
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "State": "new",
  • "SubState": "idle",
  • "Status": "ok",
  • "Labels": {
    },
  • "WWN": "string"
}

Delete a volume

Deletes the volume with the matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
volumeId
required
string

ID of volume to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

Attach existing volume to Host

Attaches the indicated volume to a host identified in the requestBody. This attachment will create a VolumeAttachment object that contains details about the connection of the volume and will update the Host with iSCSI configuration information.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
volumeId
required
string

ID of volume to attach

+
Request Body schema: application/json

Unique ID of the Host to which the volume will be attached

+
HostID
required
string <uuid>

Unique ID of the Host to attach or detach volume

+

Responses

Request samples

Content type
application/json
{
  • "HostID": "22c71c70-ebdd-4620-b802-6650e1973329"
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "VolumeID": "6a9f9b5e-05e4-4f5d-a302-ef4819ffdcf8",
  • "HostID": "22c71c70-ebdd-4620-b802-6650e1973329",
  • "HostIPAddress": "192.168.0.1",
  • "IQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "CHAPSecret": "string",
  • "CHAPUserName": "string",
  • "LUN": 0,
  • "VolumeTargetIQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "VolumeTargetIPAddress": "192.168.0.1",
  • "State": "new",
  • "FSConfig": {
    }
}

Detach existing volume from Host

Detaches the indicated volume from the host identified in the requestBody. This detachment will delete the VolumeAttachment object that contains details about the connection of the volume and will update the Host to remove selected iSCSI configuration information. +Note that the HostID is required in the body of the request to ensure that the operation is well understood and that a volume is not accidently being removed from the wrong host.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
volumeId
required
string

ID of volume to attach

+
Request Body schema: application/json

Unique ID of the Host from which a volume will be detached

+
HostID
required
string <uuid>

Unique ID of the Host to attach or detach volume

+

Responses

Request samples

Content type
application/json
{
  • "HostID": "22c71c70-ebdd-4620-b802-6650e1973329"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

volume-attachments

Operations related to VolumeAttachments that describe how a host is connected to a volume.

+

List all volume attachments in project

Returns an array of all VolumeAttachments defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new VolumeAttachment

Adds a new VolumeAttachment which enables a machine to use a volume. Note that this API is for creation of a VolumeAttachment for non-Hosts. A VolumeAttachment resource must be deleted using the 'DELETE /volume-attachments/{attachmentId}' API. For regular hosts, a VolumeAttachment is created via the 'POST /volumes/{volumeId}/attach' API.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

NewVolumeAttachement parameters to create a new VolumeAttachment.

+
Name
string

Name for the volume attachment. Must be 128 or fewer printable characters

+
VolumeID
required
string <uuid>

Unique ID of the volume attached to the host

+
required
object (ProtocolParameters)

Responses

Request samples

Content type
application/json
{
  • "Name": "My Object Name",
  • "VolumeID": "6a9f9b5e-05e4-4f5d-a302-ef4819ffdcf8",
  • "Protocol": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "VolumeID": "6a9f9b5e-05e4-4f5d-a302-ef4819ffdcf8",
  • "HostID": "22c71c70-ebdd-4620-b802-6650e1973329",
  • "HostIPAddress": "192.168.0.1",
  • "IQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "CHAPSecret": "string",
  • "CHAPUserName": "string",
  • "LUN": 0,
  • "VolumeTargetIQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "VolumeTargetIPAddress": "192.168.0.1",
  • "State": "new",
  • "FSConfig": {
    }
}

Retrieve volume attachment by ID

Returns a single volume attachment with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
attachmentId
required
string

ID of volume attachment to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "VolumeID": "6a9f9b5e-05e4-4f5d-a302-ef4819ffdcf8",
  • "HostID": "22c71c70-ebdd-4620-b802-6650e1973329",
  • "HostIPAddress": "192.168.0.1",
  • "IQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "CHAPSecret": "string",
  • "CHAPUserName": "string",
  • "LUN": 0,
  • "VolumeTargetIQN": "iqn.yyyy-mm.naming-authority:unique name",
  • "VolumeTargetIPAddress": "192.168.0.1",
  • "State": "new",
  • "FSConfig": {
    }
}

Delete a VolumeAttachment

Deletes the VolumeAttachment with the matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
attachmentId
required
string

ID of VolumeAttachment to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

networks

Operations related to Networks.

+

List all networks in project

Returns an array of all network objects defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a new network

Adds a new network that can be referenced when creating a Host

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
Request Body schema: application/json

Network that is to be added to the project

+
Name
required
string

Name of the network

+
LocationID
required
string <uuid> (LocationID)

The location ID is the data center location of the resource. The LocationID must be one of those provided by the LocationInfo array returned as part of the get /available-resources call. The locations are typically described by country, region, and data center.

+
Description
string
HostUse
string (NetworkHostUse)
Enum: "Required" "Default" "Optional"

Indicates whether use of the network is required, default, or optional. If the network is required, any new create host request for that location must include this network among the requested networks. Default and Optional are both optional networks, but imply whether they should show up initially in pre-populated fields in a graphical user interface.

+
Purpose
string (NetworkPurpose)
Enum: "Backup" "Storage" "vmKernel" "vmNSX-T" "vMotion" "vCHA" "vmFT" "iSCSI-A" "iSCSI-B" "Telemetry"

Indicates the purpose of the network.

+
object or null (NewIPPool)

Responses

Request samples

Content type
application/json
{
  • "Name": "Private2",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Description": "Private network for intra-cluster communication",
  • "HostUse": "Default",
  • "Purpose": "Storage",
  • "NewIPPool": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Description": "Private network for intra-cluster communication",
  • "HostUse": "Default",
  • "Purpose": "Storage",
  • "IPPoolID": "string",
  • "VLAN": 0,
  • "VNI": 0
}

Retrieve network by ID

Returns a single network with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
networkId
required
string

ID of network to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Description": "Private network for intra-cluster communication",
  • "HostUse": "Default",
  • "Purpose": "Storage",
  • "IPPoolID": "string",
  • "VLAN": 0,
  • "VNI": 0
}

Update an existing network.

Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
networkId
required
string

ID of network to update

+
Request Body schema: application/json

Updated network

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
LocationID
string <uuid> (LocationID)

The location ID is the data center location of the resource. The LocationID must be one of those provided by the LocationInfo array returned as part of the get /available-resources call. The locations are typically described by country, region, and data center.

+
Description
string
HostUse
string (NetworkHostUse)
Enum: "Required" "Default" "Optional"

Indicates whether use of the network is required, default, or optional. If the network is required, any new create host request for that location must include this network among the requested networks. Default and Optional are both optional networks, but imply whether they should show up initially in pre-populated fields in a graphical user interface.

+
Purpose
string (NetworkPurpose)
Enum: "Backup" "Storage" "vmKernel" "vmNSX-T" "vMotion" "vCHA" "vmFT" "iSCSI-A" "iSCSI-B" "Telemetry"

Indicates the purpose of the network.

+
IPPoolID
string
VLAN
integer

VLAN ID of the network

+
VNI
integer

VNI ID of the network

+

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Description": "Private network for intra-cluster communication",
  • "HostUse": "Default",
  • "Purpose": "Storage",
  • "IPPoolID": "string",
  • "VLAN": 0,
  • "VNI": 0
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "LocationID": "58e992d9-6663-492c-8c5b-ecf0b1b3bfe1",
  • "Description": "Private network for intra-cluster communication",
  • "HostUse": "Default",
  • "Purpose": "Storage",
  • "IPPoolID": "string",
  • "VLAN": 0,
  • "VNI": 0
}

Delete a network

Deletes the network with the matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
networkId
required
string

ID of network to delete

+

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "details": "string"
}

available-resources

Operations related to listing information that is needed to construct create host and create volume calls. This provides a detailed information about the OS imaging options, the machine size (a.k.a. Compute Instance Type) options, the storage volume options, data center locations, and such that are needed when creating hosts and volumes.

+

Get lists of available resources for creating hosts and volumes

Used to get lists of options that are used when creating hosts and volumes. A get /available-resources will return an object that includes the following arrays:

+
    +

  • Images - A list of image service IDs along with their category (Linux), +flavor (ubuntu), and version (18.04)

    +
    • +

  • MachineSizes - A list of machine size IDs along with the machine size +names and detailed descriptions

    +
    • +

  • Locations - A list of location IDs along with their country, region, +and data center.

    +
    • +

  • Networks - A list of available Network IDs along with the network name, +location ID, network kind, and host usage (Required, Default, Optional)

    +
    • +

  • MachineInventory - Information about the available inventory of machines +based on location ID and machine size ID. While this information may +change rapidly, it can be used by GUIs and systems to restrict host +creates to locations with the desired machine size.

    +
    • +

  • StorageInventory - Information about the current available storage capacity +for a specific volume flavor by site.

    +
    • +

  • VolumeFlavors - A list of volume flavor IDs along with their name and +detailed description.

    +
    • +

  • Volumes - A list of current, existing volumes. If the volume is in the +the right state, it could be attached to a new Host.

    +
    • +
+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
{
  • "Images": [
    ],
  • "Locations": [
    ],
  • "Networks": [
    ],
  • "MachineSizes": [
    ],
  • "VolumeFlavors": [
    ],
  • "Volumes": [
    ],
  • "MachineInventory": [
    ],
  • "StorageInventory": [
    ],
  • "SSHKeys": [
    ]
}

usage-reports

Operations related to retrieving information about resource usage within the project.

+

Get a usage report

Creates and returns a usage report based on the parameters passed in the request body

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
query Parameters
start
required
string

Start of the billing period

+
end
string

End of the billing period, default to now if omitted

+

Responses

Response samples

Content type
application/json
{
  • "Hosts": [
    ],
  • "Volumes": [
    ]
}

projects-info

Operations related to listing information related to projects.

+

List of all projects info within an organization or cluster for which user is authorized.

Returns an object with information on projects, machine sizes, and volume flavors. The 'Projects' list includes projects authorized for a user, and the 'MachineSizes' and 'VolumeFlavors' list include only those machine sizes and volume flavors permitted for projects.

+

When GreenLake IAM issued token is used for authentication, it is required to pass either 'Space' or 'spaceid' header. When both are set, 'Space' header is ignored.

+
Authorizations:
(BearerAuthMembership) BearerAuth
query Parameters
siteid
string
Example: siteid=95688cf9-82ff-4e32-80fc-2b0b41648dab

GreenLake site ID

+
header Parameters
Space
string
Example: Default

GreenLake space name

+
spaceid
string
Example: 95688cf9-82ff-4e32-80fc-2b0b41648dab

GreenLake space ID

+

Responses

Response samples

Content type
application/json
{
  • "Projects": [
    ],
  • "MachineSizes": [
    ],
  • "VolumeFlavors": [
    ],
  • "Summary": {
    }
}

ippools

Operations related to IP pools.

+

List all ip pools in project

Returns an array of all ip pool objects defined within the project.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve IP pool by ID

Returns a single ip pool with matching ID

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
ippoolId
required
string

ID of IP pool to return

+

Responses

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of IP pool",
  • "IPVersion": "IPv4",
  • "NetworkID": "59047804-7c6d-4fea-bf89-08c54543dccc",
  • "BaseIP": "10.128.0.0",
  • "Netmask": "/8",
  • "DefaultRoute": "10.128.0.1",
  • "Sources": [
    ],
  • "UseRecords": [
    ],
  • "DNS": [
    ],
  • "Proxy": "http://proxy.firewall.com:8080/ or http://user:password@proxy.firewall.com:8080",
  • "NoProxy": "localhost,15.10.0.10,test.com",
  • "NTP": [
    ],
  • "Pool": {
    }
}

Update IP pool by ID

Update a single ip pool with matching ID. 'DefaultRoute' can only be updated if ip pool is not currently in-use.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
ippoolId
required
string

ID of IP pool to update

+
Request Body schema: application/json

Update IPPool

+
ID
required
string <uuid>

Unique ID for the resource instance as generated by the Metal service

+
ETag
required
string <uuid>

Used to determine whether the DB entry has changed since it was last read. This value is updated each time the resource is updated. Client must send this value unchanged for any update operation.

+
Name
required
string

Common name for the resource instance. Must be 128 or fewer printable characters

+
Created
string <date-time>

Time when the resource was created in the database

+
Modified
string <date-time>

Time when the resource was last modified in the database

+
Description
required
string
IPVersion
string (IPVer)
Enum: "IPv4" "IPv6"

Describes the IP version

+
NetworkID
string <uuid>

Unique ID of the network associated with the IP pool

+
BaseIP
string

Base address of the IP pool

+
Netmask
string (Netmask)
Enum: "/8" "/9" "/10" "/11" "/12" "/13" "/14" "/15" "/16" "/17" "/18" "/19" "/20" "/21" "/22" "/23" "/24" "/25" "/26" "/27" "/28" "/29" "/30" "/31" "/104" "/105" "/106" "/107" "/108" "/109" "/110" "/111" "/112" "/113" "/114" "/115" "/116" "/117" "/118" "/119" "/120" "/121" "/122" "/123" "/124" "/125" "/126" "/127"
DefaultRoute
required
string

Default route associated with the IP pool

+
Array of objects (IPSource)
Array of objects (UseRecord)
DNS
required
Array of strings

List of DNS servers for the IP pool

+
Proxy
required
string

Optional web-proxy for external internet access should the pool actually be behind a firewall

+
NoProxy
required
string

Addresses or CIDRs for which proxy requests are not made

+
NTP
required
Array of strings

List of NTP servers for the IP pool

+
object (Pool)

Responses

Request samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of IP pool",
  • "IPVersion": "IPv4",
  • "NetworkID": "59047804-7c6d-4fea-bf89-08c54543dccc",
  • "BaseIP": "10.128.0.0",
  • "Netmask": "/8",
  • "DefaultRoute": "10.128.0.1",
  • "Sources": [
    ],
  • "UseRecords": [
    ],
  • "DNS": [
    ],
  • "Proxy": "http://proxy.firewall.com:8080/ or http://user:password@proxy.firewall.com:8080",
  • "NoProxy": "localhost,15.10.0.10,test.com",
  • "NTP": [
    ],
  • "Pool": {
    }
}

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of IP pool",
  • "IPVersion": "IPv4",
  • "NetworkID": "59047804-7c6d-4fea-bf89-08c54543dccc",
  • "BaseIP": "10.128.0.0",
  • "Netmask": "/8",
  • "DefaultRoute": "10.128.0.1",
  • "Sources": [
    ],
  • "UseRecords": [
    ],
  • "DNS": [
    ],
  • "Proxy": "http://proxy.firewall.com:8080/ or http://user:password@proxy.firewall.com:8080",
  • "NoProxy": "localhost,15.10.0.10,test.com",
  • "NTP": [
    ],
  • "Pool": {
    }
}

Allocate IPs from the pool

Allocate IPs from the pool

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
ippoolId
required
string

ID of IP pool to allocate IPs

+
Request Body schema: application/json

IPs being requested starting from an optional base IP and their usage

+
Array
Base
required
string

An optional base address for the allocation, if not specified first available address from the pool will be the base

+
Count
required
integer

Number of addresses to allocate starting from the base

+
Usage
required
string

A short description for the allocation

+

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of IP pool",
  • "IPVersion": "IPv4",
  • "NetworkID": "59047804-7c6d-4fea-bf89-08c54543dccc",
  • "BaseIP": "10.128.0.0",
  • "Netmask": "/8",
  • "DefaultRoute": "10.128.0.1",
  • "Sources": [
    ],
  • "UseRecords": [
    ],
  • "DNS": [
    ],
  • "Proxy": "http://proxy.firewall.com:8080/ or http://user:password@proxy.firewall.com:8080",
  • "NoProxy": "localhost,15.10.0.10,test.com",
  • "NTP": [
    ],
  • "Pool": {
    }
}

Return IPs to the pool

Return IPs to the pool

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
path Parameters
ippoolId
required
string

ID of IP pool to return IPs

+
Request Body schema: application/json

IP returned to the pool

+
Array
string

Responses

Request samples

Content type
application/json
[
  • "15.0.0.1"
]

Response samples

Content type
application/json
{
  • "ID": "3892eb50-4697-4c72-aadc-32b766bce3c0",
  • "ETag": "a8a0a8d9-d35b-45c6-840f-2b3694efc394",
  • "Name": "My Object Name",
  • "Created": "2019-06-27T22:59:01.661Z",
  • "Modified": "2020-02-27T18:28:02.863Z",
  • "Description": "Description of IP pool",
  • "IPVersion": "IPv4",
  • "NetworkID": "59047804-7c6d-4fea-bf89-08c54543dccc",
  • "BaseIP": "10.128.0.0",
  • "Netmask": "/8",
  • "DefaultRoute": "10.128.0.1",
  • "Sources": [
    ],
  • "UseRecords": [
    ],
  • "DNS": [
    ],
  • "Proxy": "http://proxy.firewall.com:8080/ or http://user:password@proxy.firewall.com:8080",
  • "NoProxy": "localhost,15.10.0.10,test.com",
  • "NTP": [
    ],
  • "Pool": {
    }
}

allocation

Operations related to listing information about allocation by servers and storage.

+

Get servers allocation

Returns an array of allocation information for each server instance type used by each PCE service. If siteID is present, the information returned is specific to that site ID, otherwise the allocation information for all sites is returned.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
query Parameters
siteID
string

site ID

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get storage allocation

Returns an array of allocation information for each volume type used by each PCE service. If siteID is present, the information returned is specific to that site ID, otherwise the allocation information for all sites is returned.

+
Authorizations:
(BearerAuthProject) (BearerAuthMembership)
query Parameters
siteID
string

site ID

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]
+ + + + \ No newline at end of file