List backup policies

GET /backup_policies

This request lists backup policies in the region. Backup policies control which sources are selected for backup and include a set of backup policy plans that provide the backup schedules and deletion triggers.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read
• is.backup-policy.backup-policy.list

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-policy.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

tag

Filters the collection to resources with an item in the `tags` property matching the exact specified tag.

Response

200 - The backup policies were retrieved successfully

backup_policies

array

A page of backup policies

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

Create a backup policy

POST /backup_policies

This request creates a new backup policy from a backup policy prototype object. The prototype object is structured in the same way as a retrieved backup policy, and contains the information necessary to create the new backup policy.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.create

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-policy.create

Request

Request Body

BackupPolicyPrototype

The backup policy prototype object

match_resource_type

Required *

string

The resource type this backup policy will apply to. Resources that have both a matching type and a matching user tag will be subject to the backup policy.

match_user_tags

Required *

array

The user tags this backup policy will apply to. Resources that have both a matching user tag and a matching type will be subject to the backup policy.

name

string

The name for this backup policy. The name must not be used by another backup policy in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.

plans

array

The prototype objects for backup plans to be created for this backup policy.

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

scope

BackupPolicyScopePrototype

The scope to use for this backup policy.

If unspecified, the policy will be scoped to the account.

Response

201 - The backup policy was created successfully.

created_at

string

The date and time that the backup policy was created

crn

string

The CRN for this backup policy

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this backup policy

id

string

The unique identifier for this backup policy

last_job_completed_at

string

The date and time that the most recent job for this backup policy completed.

If absent, no job has yet completed for this backup policy.

lifecycle_state

object

The lifecycle state of the backup policy

match_resource_type

string

The resource type this backup policy applies to. Resources that have both a matching type and a matching user tag will be subject to the backup policy.

The enumerated values for this property may expand in the future.

match_user_tags

array

The user tags this backup policy applies to. Resources that have both a matching user tag and a matching type will be subject to the backup policy.

name

string

The name for this backup policy. The name is unique across all backup policies in the region.

plans

array

The plans for the backup policy.

resource_group

object

The resource group for this backup policy

resource_type

string

The resource type

scope

BackupPolicyScope

The scope for this backup policy.

400 - An invalid backup policy prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The backup policy prototype object conflicts with another backup policy in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List jobs for a backup policy

GET /backup_policies/{backup_policy_id}/jobs

This request retrieves jobs for a backup policy. A backup job represents the execution of a backup policy plan for a resource matching the policy's criteria.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-job.read

Request

Path Parameters

Query Parameters

status

Filters the collection to backup policy jobs with a `status` property matching the specified value.

backup_policy_plan.id

Filters the collection to backup policy jobs with a `backup_policy_plan.id` property matching the specified identifier.

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

source.id

Filters the collection to backup policy jobs with a `source.id` property matching the specified identifier.

target_snapshots[].id

Filters the collection to backup policy jobs with an item in the `target_snapshots` property with an `id` property matching the specified identifier.

target_snapshots[].crn

string

Filters the collection to backup policy jobs with an item in the `target_snapshots` property with a `crn` property matching the specified CRN.

Response

200 - The backup policy jobs were retrieved successfully.

first

object

A link to the first page of resources

jobs

array

A page of jobs for the backup policy

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a backup policy job

GET /backup_policies/{backup_policy_id}/jobs/{id}

This request retrieves a single backup policy job specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-job.read

Request

Response

200 - The backup policy job was retrieved successfully.

auto_delete

boolean

Indicates whether this backup policy job will be automatically deleted after it completes. At present, this is always `true`, but may be modifiable in the future.

auto_delete_after

integer

If `auto_delete` is `true`, the days after completion that this backup policy job will be deleted. This value may be modifiable in the future.

backup_policy_plan

object

The backup policy plan operated this backup policy job (may be deleted).

completed_at

string

The date and time that the backup policy job was completed.

If absent, the backup policy job has not yet completed.

created_at

string

The date and time that the backup policy job was created

href

string

The URL for this backup policy job

id

string

The unique identifier for this backup policy job

job_type

string

The type of backup policy job.

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

source

BackupPolicyJobSource

The source this backup was created from (may be deleted).

status

object

The status of the backup policy job.

The enumerated values for this property may expand in the future.

status_reasons

array

The reasons for the current status (if any).

target_snapshots

array

The snapshots operated on by this backup policy job (may be deleted).

404 - A backup policy job with the specified identifier could not be found for the backup

policy with the specified identifier.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List plans for a backup policy

GET /backup_policies/{backup_policy_id}/plans

This request retrieves plans for a backup policy. Backup plans provide the backup schedule and deletion triggers.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-plan.read

Request

Path Parameters

Query Parameters

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

Response

200 - The backup policy plans were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

plans

array

A page of plans for the backup policy

total_count

integer

The total number of resources across all pages

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

POST /backup_policies/{backup_policy_id}/plans

This request creates a new backup policy plan from a backup policy plan prototype object. The prototype object is structured in the same way as a retrieved backup policy plan, and contains the information necessary to create the new backup policy plan.

Backups created by this plan will use the resource group of the source being backed up.

Backups created by this plan will use the plan's name truncated to 46 characters, followed by a unique 16-character suffix.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.update

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-plan.create

Request

Request Body

BackupPolicyPlanPrototype

The backup policy plan prototype object

active

boolean

Indicates whether the plan is active.

attach_user_tags

array

The user tags to attach to each backup (snapshot) created by this plan.

clone_policy

BackupPolicyPlanClonePolicyPrototype

max_snapshots

integer

The maximum number of recent snapshots (per source) that will keep clones.

zones

Required *

array

The zone this backup policy plan will create snapshot clones in.

copy_user_tags

boolean

Indicates whether to copy the source's user tags to the created backups (snapshots).

cron_spec

Required *

string

The cron specification for the backup schedule. The backup policy jobs (which create and delete backups for this plan) will not start until this time, and may start for up to 90 minutes after this time.

All backup schedules for plans in the same policy must be at least an hour apart.

deletion_trigger

BackupPolicyPlanDeletionTriggerPrototype

delete_after

integer

The maximum number of days to keep each backup after creation.

delete_over_count

integer

The maximum number of recent backups to keep. If unspecified, there will be no maximum.

name

string

The name for this backup policy plan. The name must not be used by another plan for the backup policy. If unspecified, the name will be a hyphenated list of randomly-selected words.

remote_region_policies

array

The policies for additional backups in remote regions.

Response

201 - The backup policy plan was created successfully.

active

boolean

Indicates whether the plan is active.

attach_user_tags

array

The user tags to attach to backups (snapshots) created by this plan.

clone_policy

BackupPolicyPlanClonePolicy

copy_user_tags

boolean

Indicates whether to copy the source's user tags to the created backups (snapshots).

created_at

string

The date and time that the backup policy plan was created

cron_spec

string

The cron specification for the backup schedule. The backup policy jobs (which create and delete backups for this plan) will not start until this time, and may start for up to 90 minutes after this time.

All backup schedules for plans in the same policy must be at least an hour apart.

deletion_trigger

BackupPolicyPlanDeletionTrigger

href

string

The URL for this backup policy plan

id

string

The unique identifier for this backup policy plan

lifecycle_state

object

The lifecycle state of this backup policy plan

name

string

The name for this backup policy plan. The name is unique across all plans in the backup policy.

remote_region_policies

array

The policies for additional backups in remote regions.

resource_type

string

The resource type

400 - An invalid backup policy plan prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The backup policy plan prototype object specified an encryption key that cannot

be used in its current state.

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /backup_policies/{backup_policy_id}/plans/{id}

This request deletes a backup policy plan. This operation cannot be reversed. Any backups that have been created by the plan will remain but will no longer be subject to the plan's deletion trigger. Any running jobs associated with the plan will run to completion before the plan is deleted.

If the request is accepted, the backup policy plan `status` will be set to `deleting`. Once deletion processing completes, the backup policy plan will no longer be retrievable.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.update

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-plan.delete

Request

Path Parameters

Query Parameters

Response

202 - The backup policy plan deletion request was accepted.

active

boolean

Indicates whether the plan is active.

attach_user_tags

array

The user tags to attach to backups (snapshots) created by this plan.

clone_policy

BackupPolicyPlanClonePolicy

copy_user_tags

boolean

Indicates whether to copy the source's user tags to the created backups (snapshots).

created_at

string

The date and time that the backup policy plan was created

cron_spec

string

The cron specification for the backup schedule. The backup policy jobs (which create and delete backups for this plan) will not start until this time, and may start for up to 90 minutes after this time.

All backup schedules for plans in the same policy must be at least an hour apart.

deletion_trigger

BackupPolicyPlanDeletionTrigger

href

string

The URL for this backup policy plan

id

string

The unique identifier for this backup policy plan

lifecycle_state

object

The lifecycle state of this backup policy plan

name

string

The name for this backup policy plan. The name is unique across all plans in the backup policy.

remote_region_policies

array

The policies for additional backups in remote regions.

resource_type

string

The resource type

404 - A backup policy plan with the specified identifier could not be found for the policy

plan with the specified identifier.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the backup

policy plan.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a backup policy plan

GET /backup_policies/{backup_policy_id}/plans/{id}

This request retrieves a single backup policy plan specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-plan.read

Request

Response

200 - The backup policy plan was retrieved successfully.

active

boolean

Indicates whether the plan is active.

attach_user_tags

array

The user tags to attach to backups (snapshots) created by this plan.

clone_policy

BackupPolicyPlanClonePolicy

copy_user_tags

boolean

Indicates whether to copy the source's user tags to the created backups (snapshots).

created_at

string

The date and time that the backup policy plan was created

cron_spec

string

The cron specification for the backup schedule. The backup policy jobs (which create and delete backups for this plan) will not start until this time, and may start for up to 90 minutes after this time.

All backup schedules for plans in the same policy must be at least an hour apart.

deletion_trigger

BackupPolicyPlanDeletionTrigger

href

string

The URL for this backup policy plan

id

string

The unique identifier for this backup policy plan

lifecycle_state

object

The lifecycle state of this backup policy plan

name

string

The name for this backup policy plan. The name is unique across all plans in the backup policy.

remote_region_policies

array

The policies for additional backups in remote regions.

resource_type

string

The resource type

404 - A backup policy plan with the specified identifier could not be found for the backup

policy with the specified identifier.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a backup policy plan

PATCH /backup_policies/{backup_policy_id}/plans/{id}

This request updates a backup policy plan with the information in a provided plan patch. The plan patch object is structured in the same way as a retrieved backup policy plan and can contains only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.update

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-plan.update

Request

Request Body

The backup policy plan patch

Path Parameters

Query Parameters

Response

200 - The backup policy plan was updated successfully.

active

boolean

Indicates whether the plan is active.

attach_user_tags

array

The user tags to attach to backups (snapshots) created by this plan.

clone_policy

BackupPolicyPlanClonePolicy

copy_user_tags

boolean

Indicates whether to copy the source's user tags to the created backups (snapshots).

created_at

string

The date and time that the backup policy plan was created

cron_spec

string

The cron specification for the backup schedule. The backup policy jobs (which create and delete backups for this plan) will not start until this time, and may start for up to 90 minutes after this time.

All backup schedules for plans in the same policy must be at least an hour apart.

deletion_trigger

BackupPolicyPlanDeletionTrigger

href

string

The URL for this backup policy plan

id

string

The unique identifier for this backup policy plan

lifecycle_state

object

The lifecycle state of this backup policy plan

name

string

The name for this backup policy plan. The name is unique across all plans in the backup policy.

remote_region_policies

array

The policies for additional backups in remote regions.

resource_type

string

The resource type

400 - An invalid backup policy plan patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A backup policy plan with the specified identifier could not be found for the backup

policy with the specified identifier.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The specified encryption key cannot be used in its current state.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the backup

policy plan.

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /backup_policies/{id}

This request deletes a backup policy. This operation cannot be reversed.

If the request is accepted, the backup policy `status` will be set to `deleting`. Once deletion processing completes, the backup policy will no longer be retrievable.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.delete

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-policy.delete

Request

Path Parameters

Query Parameters

Response

202 - The backup policy deletion request was accepted.

created_at

string

The date and time that the backup policy was created

crn

string

The CRN for this backup policy

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this backup policy

id

string

The unique identifier for this backup policy

last_job_completed_at

string

The date and time that the most recent job for this backup policy completed.

If absent, no job has yet completed for this backup policy.

lifecycle_state

object

The lifecycle state of the backup policy

match_resource_type

string

The resource type this backup policy applies to. Resources that have both a matching type and a matching user tag will be subject to the backup policy.

The enumerated values for this property may expand in the future.

match_user_tags

array

The user tags this backup policy applies to. Resources that have both a matching user tag and a matching type will be subject to the backup policy.

name

string

The name for this backup policy. The name is unique across all backup policies in the region.

plans

array

The plans for the backup policy.

resource_group

object

The resource group for this backup policy

resource_type

string

The resource type

scope

BackupPolicyScope

The scope for this backup policy.

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the backup

policy.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a backup policy

GET /backup_policies/{id}

This request retrieves a single backup policy specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.read

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-policy.read

Request

Response

200 - The backup policy was retrieved successfully.

created_at

string

The date and time that the backup policy was created

crn

string

The CRN for this backup policy

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this backup policy

id

string

The unique identifier for this backup policy

last_job_completed_at

string

The date and time that the most recent job for this backup policy completed.

If absent, no job has yet completed for this backup policy.

lifecycle_state

object

The lifecycle state of the backup policy

match_resource_type

string

The resource type this backup policy applies to. Resources that have both a matching type and a matching user tag will be subject to the backup policy.

The enumerated values for this property may expand in the future.

match_user_tags

array

The user tags this backup policy applies to. Resources that have both a matching user tag and a matching type will be subject to the backup policy.

name

string

The name for this backup policy. The name is unique across all backup policies in the region.

plans

array

The plans for the backup policy.

resource_group

object

The resource group for this backup policy

resource_type

string

The resource type

scope

BackupPolicyScope

The scope for this backup policy.

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a backup policy

PATCH /backup_policies/{id}

This request updates a backup policy with the information in a provided backup policy patch. The backup policy patch object is structured in the same way as a retrieved backup policy and contains only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.backup-policy.backup-policy.update

Auditing

Calling this method generates the following auditing event.

• is.backup-policy.backup-policy.update

Request

Request Body

The backup policy patch

Path Parameters

Query Parameters

Response

200 - The backup policy was updated successfully.

created_at

string

The date and time that the backup policy was created

crn

string

The CRN for this backup policy

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this backup policy

id

string

The unique identifier for this backup policy

last_job_completed_at

string

The date and time that the most recent job for this backup policy completed.

If absent, no job has yet completed for this backup policy.

lifecycle_state

object

The lifecycle state of the backup policy

match_resource_type

string

The resource type this backup policy applies to. Resources that have both a matching type and a matching user tag will be subject to the backup policy.

The enumerated values for this property may expand in the future.

match_user_tags

array

The user tags this backup policy applies to. Resources that have both a matching user tag and a matching type will be subject to the backup policy.

name

string

The name for this backup policy. The name is unique across all backup policies in the region.

plans

array

The plans for the backup policy.

resource_group

object

The resource group for this backup policy

resource_type

string

The resource type

scope

BackupPolicyScope

The scope for this backup policy.

400 - An invalid backup policy patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A backup policy with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The backup policy patch conflicts with another backup policy in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the backup

policy.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List capacities for bare metal servers

GET /bare_metal_server/capacities

This request lists bare metal server capacities in the region.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.capacity.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

profile.name

string

Filters the collection to resources with a `profile.name` property matching the specified profile name.

zone.name

string

Filters the collection to resources with a `zone.name` property matching the exact specified name.

Response

200 - The available bare metal server capacities were retrieved successfully

capacities

array

A page of available bare metal server capacities.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

List bare metal server profiles

GET /bare_metal_server/profiles

This request lists bare metal server profiles available in the region. A bare metal server profile specifies the performance characteristics and pricing model for a bare metal server.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.profile.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The bare metal server profiles were retrieved successfully

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

profiles

array

A page of bare metal server profiles

total_count

integer

The total number of resources across all pages

Retrieve a bare metal server profile

GET /bare_metal_server/profiles/{name}

This request retrieves a single bare metal server profile specified by the name in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.profile.read

Request

Path Parameters

name

Required *

string

The bare metal server profile name

Query Parameters

Response

200 - The bare metal server profile was retrieved successfully

bandwidth

BareMetalServerProfileBandwidth

console_types

BareMetalServerProfileConsoleTypes

The console type configuration for a bare metal server with this profile.

cpu_architecture

BareMetalServerProfileCPUArchitecture

cpu_core_count

BareMetalServerProfileCPUCoreCount

cpu_socket_count

BareMetalServerProfileCPUSocketCount

disks

BareMetalServerProfileDisks

The disks for a bare metal server with this profile.

family

string

The product family this bare metal server profile belongs to

href

string

The URL for this bare metal server profile

memory

BareMetalServerProfileMemory

name

string

The name for this bare metal server profile

network_attachment_count

BareMetalServerProfileNetworkAttachmentCount

network_interface_count

BareMetalServerProfileNetworkInterfaceCount

os_architecture

BareMetalServerProfileOSArchitecture

reservation_terms

BareMetalServerProfileReservationTerms

resource_type

string

The resource type

supported_trusted_platform_module_modes

BareMetalServerProfileSupportedTrustedPlatformModuleModes

The supported trusted platform module modes for this bare metal server profile.

supported_volume_attachment_protocols

array

The volume attachment protocols supported by bare metal servers that use this profile. These protocols determine how block storage volumes can be attached to servers created from the profile. An empty array indicates that the profile does not support volume attachments.

• `nvme_tcp`: Non-Volatile Memory Express (NVMe) over TCP/IP. This protocol allows bare metal servers to connect to volumes over the network using the NVMe protocol.

virtual_network_interfaces_supported

BareMetalServerProfileVirtualNetworkInterfacesSupported

Indicates whether this profile supports virtual network interfaces

zones

BareMetalServerProfileZones

The zones in this region that support this bare metal server profile.

404 - A bare metal server profile with the specified name could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List bare metal servers

GET /bare_metal_servers

This request lists bare metal servers in the region.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.list
• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

reservation.id

Filters the collection to resources with a `reservation.id` property matching the specified identifier.

reservation.crn

string

Filters the collection to resources with a `reservation.crn` property matching the specified identifier.

reservation.name

string

Filters the collection to resources with a `reservation.name` property matching the specified identifier.

vpc.id

Filters the collection to resources with a `vpc.id` property matching the specified identifier.

vpc.crn

string

Filters the collection to resources with a `vpc.crn` property matching the specified CRN.

vpc.name

string

Filters the collection to resources with a `vpc.name` property matching the exact specified name.

Response

200 - The bare metal servers were retrieved successfully.

bare_metal_servers

array

A page of bare metal servers

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

POST /bare_metal_servers

This request provisions a new bare metal server from a prototype object. The prototype object is structured in the same way as a retrieved bare metal server, and contains the information necessary to provision the new bare metal server. The bare metal server is automatically started.

For this request to succeed, the properties in the request must adhere to the source image's `allowed_use` property.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.create
• is.subnet.subnet.operate
• is.subnet.subnet.update
• is.security-group.security-group.operate
• is.vpc.vpc.operate
• is.key.key.operate
• is.image.image.operate
• is.bare-metal-server.bare-metal-server.ip-spoofing
• is.bare-metal-server.bare-metal-server.infrastructure-nat
• is.reservation.reservation.operate
• iam-identity.profile.get
• iam-identity.profile.update
• iam-identity.profile.linkToResource
• is.virtual-network-interface.virtual-network-interface.create
• is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat
• is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing
• is.virtual-network-interface.virtual-network-interface.manage-protocol-state-filtering-mode

Auditing

Calling this method generates the following auditing event.

• is.virtual-network-interface.virtual-network-interface.create
• is.virtual-network-interface.virtual-network-interface.attach
• is.bare-metal-server.network-attachment.attach
• is.bare-metal-server.bare-metal-server.create
• is.bare-metal-server.network-attachment.create
• is.bare-metal-server.network-interface.create
• is.bare-metal-server.network-interface.attach
• is.subnet.reserved-ip.attach
• is.subnet.reserved-ip.create
• is.security-group.security-group.attach
• is.subnet.subnet.update
• is.bare-metal-server.bare-metal-server.attach
• is.reservation.reservation.attach

Request

Request Body

BareMetalServerPrototype

The bare metal server prototype object

bandwidth

integer

The total bandwidth (in megabits per second) shared across the bare metal server's network interfaces. The specified value must match one of the bandwidth values in the bare metal server's profile. If unspecified, the default value from the profile will be used.

enable_secure_boot

boolean

Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.

initialization

Required *

BareMetalServerInitializationPrototype

default_trusted_profile

object

The default trusted profile to be used when initializing the bare metal server.

If unspecified, no default trusted profile will be made available.

keys

Required *

array

The public SSH keys to install on the bare metal server. Keys will be made available to the bare metal server as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the default user.

For Windows images, at least one SSH key of type `rsa` must be specified. One of the provided keys is selected to encrypt the administrator password. SSH keys are optional for other images; however, if no keys are specified, the bare metal server will be inaccessible unless the selected image provides an alternative access mechanism.

To allow for remote block storage attachment, at least one key of type `rsa` must be specified. One of the provided keys is selected to encrypt the `storage_access` secret. If no keys are specified, the bare metal server will be unable to connect to remote block storage until either:

• the server is reinitialized with at least one key of type `rsa`
• the `storage_access` secret is rotated with a key of type `rsa`

user_data

string

The user data to make available when setting up the bare metal server.

metadata_service

BareMetalServerMetadataServicePrototype

The metadata service configuration for the bare metal server

enabled

boolean

Indicates whether the metadata service endpoint will be available to the bare metal server

protocol

string

The communication protocol to use for the metadata service endpoint. Applies only when the metadata service is enabled.

• `http`: HTTP protocol (unencrypted)
• `https`: HTTP Secure protocol

name

string

The name for this bare metal server. The name must not be used by another bare metal server in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.

The system hostname will be based on this name.

profile

Required *

object

Identifies a bare metal server profile by a unique property.

reservation_affinity

BareMetalServerReservationAffinityPrototype

policy

string

The reservation affinity policy to use for this bare metal server:

• `disabled`: Reservations will not be used
• `manual`: Reservations in `pool` will be available for use
• `automatic`: Any reservations with an `affinity_policy` of `automatic` that have the same `profile` and `zone` as this bare metal server are available for use.

The policy will default to `manual` if `pool` is not empty. Otherwise the policy will default to `automatic`.

pool

array

The pool of reservations available for use by this bare metal server.

Specified reservations must have a `status` of `active`, and have the same `profile` and `zone` as this bare metal server.

If `policy` is `manual`, `pool` must have one reservation. If `policy` is `disabled` or `automatic`, `pool` must be empty. If `policy` is `manual`, the `pool` must contain a reservation with available capacity.

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

trusted_platform_module

BareMetalServerTrustedPlatformModulePrototype

mode

string

The trusted platform module mode to use. The specified value must be listed in the bare metal server profile's `supported_trusted_platform_module_modes`.

If unspecified, the default trusted platform module mode from the profile will be used.

volume_attachments

array

The additional volume attachments to create for the bare metal server

vpc

object

Identifies a VPC by a unique property.

zone

Required *

object

Identifies a zone by a unique property.

Response

201 - The bare metal server was created successfully.

bandwidth

integer

The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces

boot_target

BareMetalServerBootTarget

The resource from which this bare metal server is booted.

The resources supported by this property may expand in the future.

cpu

BareMetalServerCPU

The bare metal server CPU configuration

created_at

string

The date and time that the bare metal server was created

crn

string

The CRN for this bare metal server

disks

array

The disks for this bare metal server, including any disks that are associated with the `boot_target`.

enable_secure_boot

boolean

Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.

firmware

BareMetalServerFirmware

Firmware information for the bare metal server

health_reasons

array

The reasons for the current server `health_state` (if any):

• `reservation_capacity_unavailable`: The reservation affinity pool has no available capacity.
• `reservation_deleted`: The reservation affinity pool has a deleted reservation.
• `reservation_expired`: The reservation affinity pool has an expired reservation.
• `reservation_failed`: The reservation affinity pool has a failed reservation.

See health status reasons for details. The enumerated values for this property may expand in the future.

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this bare metal server

id

string

The unique identifier for this bare metal server

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the bare metal server.

memory

integer

The amount of memory, truncated to whole gibibytes

metadata_service

BareMetalServerMetadataService

The metadata service configuration for the bare metal server

name

string

The name for this bare metal server. The name is unique across all bare metal servers in the region.

network_attachments

array

The network attachments for this bare metal server, including the primary network attachment.

network_interfaces

array

The network interfaces for this bare metal server, including the primary network interface.

If this bare metal server has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.

nvme_qualified_name

object

An NVMe Qualified Name (NQN). NQNs are unique identifiers used in NVMe over Fabrics (NVMe-oF) to identify NVMe subsystems and hosts.

primary_network_attachment

object

The primary network attachment for this bare metal server.

primary_network_interface

object

The primary network interface for this bare metal server.

If this bare metal server has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.

profile

object

The profile for this bare metal server

reservation

object

The reservation used by this bare metal server. If absent, no reservation is in use.

reservation_affinity

BareMetalServerReservationAffinity

resource_group

object

The resource group for this bare metal server

resource_type

string

The resource type

status

string

The status of this bare metal server:

• `deleting`: server is undergoing deletion
• `failed`: server is failed and not usable (see `status_reasons`)
• `maintenance`: server is undergoing maintenance (not usable)
• `pending`: server is being provisioned and not yet usable
• `reinitializing`: server is reinitializing and not yet usable
• `restarting`: server is restarting and not yet usable
• `running`: server is powered on
• `starting`: server is starting and not yet usable
• `stopped`: server is powered off

The enumerated values for this property may expand in the future.

status_reasons

array

The reasons for the current status (if any).

storage_access

object

The storage access secret required to connect to remote storage.

This property will be present if an SSH Key of type `rsa` was provided during server initialization, reinitialization, or `storage_access` secret rotation.

trusted_platform_module

BareMetalServerTrustedPlatformModule

volume_attachments

array

The volume attachments for this bare metal server.

This array will be empty if no volumes are attached to the bare metal server.

vpc

object

The VPC this bare metal server resides in

zone

object

The zone this bare metal server resides in

400 - An invalid bare metal server prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server prototype object conflicts with another bare metal server

in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve the console WebSocket for a bare metal server

GET /bare_metal_servers/{bare_metal_server_id}/console

This retrieves a WebSocket providing a console for the bare metal server. An `access_token` must first be created using the `console_access_token` API. The `serial` WebSocket provides a TTY based interface. The `vnc` WebSocket provides a VNC based graphical interface. For this request to succeed, the server must have a `status` of `stopped`, `starting`, or `running`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate
• is.bare-metal-server.bare-metal-server.console

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.console.read

Request

Path Parameters

Query Parameters

access_token

A URL safe single-use token used to access the console WebSocket.

Response

101 - A WebSocket connection was established.

400 - The open console limit for bare metal servers was reached.

errors

array

The errors that occurred.

trace

string

The unique error identifier

401 - An invalid bare metal server console access token was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - A console WebSocket cannot be retrieved in the server's current state.

errors

array

The errors that occurred.

trace

string

The unique error identifier

426 - The WebSocket protocol is required.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a console access token for a bare metal server

POST /bare_metal_servers/{bare_metal_server_id}/console_access_token

This request creates a new single-use console access token for a bare metal server. All console configuration is provided at token create time, and the token is subsequently used in the `access_token` query parameter for the WebSocket request. The access token is only valid for a short period of time, and a maximum of one token is valid for a given bare metal server at a time. For this request to succeed, the server must have a `status` of `stopped`, `starting`, or `running`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate
• is.bare-metal-server.bare-metal-server.console

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.console.read

Request

Request Body

BareMetalServerConsoleAccessTokenPrototype

The bare metal server console access token prototype

console_type

Required *

string

The bare metal server console type for which this token may be used

Must be `serial` for bare metal servers with a `cpu.architecture` of `s390x`

force

boolean

Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.

Response

200 - The access token was created successfully.

access_token

string

A URL safe single-use token used to access the console WebSocket.

console_type

string

The bare metal server console type for which this token may be used

created_at

string

The date and time that the access token was created

expires_at

string

The date and time that the access token will expire

force

boolean

Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.

href

string

The URL to access this bare metal server console.

400 - An invalid bare metal server console access token prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The bare metal server console access token is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - A console access token cannot be created in the server's current state.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List disks on a bare metal server

GET /bare_metal_servers/{bare_metal_server_id}/disks

This request lists disks on a bare metal server. A disk is a block device that is locally attached to the physical server. By default, the listed disks are sorted by their `created_at` property values, with the newest disk first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.disk.read

Request

Response

200 - The disks were retrieved successfully.

disks

array

The disks for the bare metal server

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a bare metal server disk

GET /bare_metal_servers/{bare_metal_server_id}/disks/{id}

This request retrieves a single disk specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.disk.read

Request

Response

200 - The disk was retrieved successfully.

allowed_use

object

The usage constraints to be matched against the requested bare metal server properties to determine compatibility.

Only present for disks which are referenced in a bare metal server's `boot_target` property. The value of this property will be inherited from the source image at creation.

created_at

string

The date and time that the disk was created

href

string

The URL for this bare metal server disk

id

string

The unique identifier for this bare metal server disk

interface_type

string

The disk attachment interface used:

• `fcp`: Fiber Channel Protocol
• `sata`: Serial Advanced Technology Attachment
• `nvme`: Non-Volatile Memory Express

The enumerated values for this property may expand in the future.

name

string

The name for this bare metal server disk. The name is unique across all disks on the bare metal server.

resource_type

string

The resource type

size

integer

The size of the disk in GB (gigabytes)

404 - A bare metal server disk with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a bare metal server disk

PATCH /bare_metal_servers/{bare_metal_server_id}/disks/{id}

This request updates the bare metal server disk with the information in a provided patch.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.disk.update

Request

Request Body

The bare metal server disk patch

Response

200 - The bare metal server disk was updated successfully.

allowed_use

object

The usage constraints to be matched against the requested bare metal server properties to determine compatibility.

Only present for disks which are referenced in a bare metal server's `boot_target` property. The value of this property will be inherited from the source image at creation.

created_at

string

The date and time that the disk was created

href

string

The URL for this bare metal server disk

id

string

The unique identifier for this bare metal server disk

interface_type

string

The disk attachment interface used:

• `fcp`: Fiber Channel Protocol
• `sata`: Serial Advanced Technology Attachment
• `nvme`: Non-Volatile Memory Express

The enumerated values for this property may expand in the future.

name

string

The name for this bare metal server disk. The name is unique across all disks on the bare metal server.

resource_type

string

The resource type

size

integer

The size of the disk in GB (gigabytes)

400 - An invalid bare metal server disk patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The bare metal server disk is not allowed to be updated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server disk with the specified identifier could not be found for the

specified bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server disk patch conflicts with another disk for the

bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /bare_metal_servers/{bare_metal_server_id}/network_attachments

This request lists network attachments on a bare metal server. A bare metal server network attachment is an abstract representation of a network device and attaches a bare metal server to a single subnet. Each network interface on a bare metal server can attach to any subnet in the zone, including subnets that are already attached to the bare metal server.

The network attachments will be sorted by their `created_at` property values, with newest network attachments first. Network attachments with identical `created_at` property values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-attachment.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The bare metal server network attachments were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

network_attachments

array

The network attachments for the bare metal server

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a network attachment on a bare metal server

POST /bare_metal_servers/{bare_metal_server_id}/network_attachments

This request creates a new bare metal server network attachment from a bare metal server network attachment prototype object. The prototype object is structured in the same way as a retrieved bare metal server network attachment, and contains the information necessary to create the new bare metal server network attachment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.security-group.security-group.operate
• is.subnet.subnet.operate
• is.subnet.subnet.update
• is.virtual-network-interface.virtual-network-interface.create
• is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat
• is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing
• is.virtual-network-interface.virtual-network-interface.manage-protocol-state-filtering-mode

Auditing

Calling this method generates the following auditing event.

• is.virtual-network-interface.virtual-network-interface.create
• is.virtual-network-interface.virtual-network-interface.attach
• is.bare-metal-server.network-attachment.attach
• is.bare-metal-server.network-attachment.create
• is.subnet.reserved-ip.create
• is.subnet.reserved-ip.attach
• is.security-group.security-group.attach
• is.subnet.subnet.update

Request

Request Body

BareMetalServerNetworkAttachmentPrototype

The bare metal server network attachment prototype object

interface_type

Required *

string

The network attachment's interface type:

• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI attachment
  • Cannot directly use an IEEE 802.1Q tag.
  • Not supported on bare metal servers with a `cpu.architecture` of `s390x`
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.
  • Not supported on bare metal servers with a `cpu.architecture` of `s390x`

name

string

The name for this bare metal server network attachment. Names must be unique within the bare metal server the network attachment resides in. If unspecified, the name will be a hyphenated list of randomly-selected words.

virtual_network_interface

Required *

BareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterface

A virtual network interface for the bare metal server network attachment. This can be specified using an existing virtual network interface, or a prototype object for a new virtual network interface.

If an existing virtual network interface is specified, it must not be the target of a flow log collector.

Response

201 - The bare metal server network attachment was created successfully.

created_at

string

The date and time that the bare metal server network attachment was created

href

string

The URL for this bare metal server network attachment

id

string

The unique identifier for this bare metal server network attachment

interface_type

string

The network attachment's interface type:

• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI attachment
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.

The enumerated values for this property may expand in the future.

lifecycle_state

object

The lifecycle state of the bare metal server network attachment

name

string

The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.

port_speed

integer

The port speed for this bare metal server network attachment in Mbps

primary_ip

object

The primary IP address of the virtual network interface for the bare metal server network attachment

resource_type

string

The resource type

subnet

object

The subnet of the virtual network interface for the bare metal server network attachment

type

string

The bare metal server network attachment type.

The enumerated values for this property may expand in the future.

virtual_network_interface

object

The virtual network interface for this bare metal server network attachment

400 - An invalid bare metal server network attachment prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server network attachment prototype object conflicts with

another network attachment for the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}

This request deletes a bare metal server network attachment. This operation cannot be reversed. Any floating IPs associated with the bare metal server network attachment are implicitly disassociated.

The bare metal server's primary network attachment cannot be deleted.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-attachment.delete
• is.virtual-network-interface.virtual-network-interface.detach
• is.virtual-network-interface.virtual-network-interface.delete
• is.floating-ip.floating-ip.detach
• is.subnet.reserved-ip.detach
• is.subnet.reserved-ip.delete
• is.subnet.subnet.update
• is.security-group.security-group.detach

Request

Response

202 - The bare metal server network attachment deletion request was accepted.

403 - The bare metal server network attachment is not allowed to be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server network attachment with the specified identifier could not be

found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a bare metal server network attachment

GET /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}

This request retrieves a single bare metal server network attachment specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-attachment.read

Request

Response

200 - The bare metal server network attachment was retrieved successfully.

created_at

string

The date and time that the bare metal server network attachment was created

href

string

The URL for this bare metal server network attachment

id

string

The unique identifier for this bare metal server network attachment

interface_type

string

The network attachment's interface type:

• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI attachment
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.

The enumerated values for this property may expand in the future.

lifecycle_state

object

The lifecycle state of the bare metal server network attachment

name

string

The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.

port_speed

integer

The port speed for this bare metal server network attachment in Mbps

primary_ip

object

The primary IP address of the virtual network interface for the bare metal server network attachment

resource_type

string

The resource type

subnet

object

The subnet of the virtual network interface for the bare metal server network attachment

type

string

The bare metal server network attachment type.

The enumerated values for this property may expand in the future.

virtual_network_interface

object

The virtual network interface for this bare metal server network attachment

404 - A bare metal server network attachment with the specified identifier could not be

found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a bare metal server network attachment

PATCH /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}

This request updates a bare metal server network attachment with the information provided in a bare metal server network attachment patch object. The bare metal server network attachment patch object is structured in the same way as a retrieved bare metal server network attachment and contains only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-attachment.update

Request

Request Body

The bare metal server network attachment patch

Response

200 - The bare metal server network attachment was updated successfully.

created_at

string

The date and time that the bare metal server network attachment was created

href

string

The URL for this bare metal server network attachment

id

string

The unique identifier for this bare metal server network attachment

interface_type

string

The network attachment's interface type:

• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI attachment
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.

The enumerated values for this property may expand in the future.

lifecycle_state

object

The lifecycle state of the bare metal server network attachment

name

string

The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.

port_speed

integer

The port speed for this bare metal server network attachment in Mbps

primary_ip

object

The primary IP address of the virtual network interface for the bare metal server network attachment

resource_type

string

The resource type

subnet

object

The subnet of the virtual network interface for the bare metal server network attachment

type

string

The bare metal server network attachment type.

The enumerated values for this property may expand in the future.

virtual_network_interface

object

The virtual network interface for this bare metal server network attachment

400 - An invalid bare metal server network attachment patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server network attachment with the specified identifier could not be

found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server network attachment patch conflicts with another

network attachment for the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List network interfaces on a bare metal server

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces

This request lists network interfaces on a bare metal server. A bare metal server network interface is an abstract representation of a network device and attaches a bare metal server to a single subnet. Each network interface on a bare metal server can attach to any subnet in the zone, including subnets that are already attached to the bare metal server.

If this bare metal server has network attachments, each returned network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The bare metal server network interfaces were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

network_interfaces

array

The network interfaces for the bare metal server

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a network interface on a bare metal server

POST /bare_metal_servers/{bare_metal_server_id}/network_interfaces

This request creates a new bare metal server network interface from a bare metal server network interface prototype object. The prototype object is structured in the same way as a retrieved bare metal server network interface, and contains the information necessary to create the new bare metal server network interface. Any subnet in the bare metal server's VPC may be specified, even if it is already attached to another bare metal server network interface. Addresses on the bare metal server network interface must be within the specified subnet's CIDR blocks.

If this bare metal server has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and new network interfaces are not allowed to be created.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.subnet.subnet.operate
• is.subnet.subnet.update
• is.security-group.security-group.operate
• is.bare-metal-server.bare-metal-server.ip-spoofing
• is.bare-metal-server.bare-metal-server.infrastructure-nat

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.create
• is.bare-metal-server.network-interface.attach
• is.subnet.reserved-ip.create
• is.subnet.reserved-ip.attach
• is.security-group.security-group.attach
• is.subnet.subnet.update

Request

Request Body

BareMetalServerNetworkInterfacePrototype

The bare metal server network interface prototype object

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and source IP spoofing is managed on the attached virtual network interface.

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the bare metal server network interface, allowing the workload to perform any needed NAT operations.
• `allow_ip_spoofing` must be `false`.
• `interface_type` must not be `hipersocket`.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and infrastructure NAT is managed on the attached virtual network interface.

interface_type

Required *

string

The interface type:

• `hipersocket`: a virtual device that provides high-speed TCP/IP connectivity within a `s390x` based system
  • Not supported on bare metal servers with a `cpu.architecture` of `amd64`
• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI interface
  • Cannot directly use an IEEE 802.1Q tag.
  • Not supported on bare metal servers with a `cpu.architecture` of `s390x`
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.
  • Has its own security groups and does not inherit those of the PCI device through which traffic flows.
  • Not supported on bare metal servers with a `cpu.architecture` of `s390x`

name

string

The name for this bare metal server network interface. The name must not be used by another network interface on the bare metal server. If unspecified, the name will be a hyphenated list of randomly-selected words.

primary_ip

object

The primary IP address to bind to the bare metal server network interface. This can be specified using an existing reserved IP, or a prototype object for a new reserved IP.

If an existing reserved IP or a prototype object with an address is specified, it must be available on the bare metal server network interface's subnet. Otherwise, an available address on the subnet will be automatically selected and reserved.

security_groups

array

The security groups to use for this bare metal server network interface. If unspecified, the VPC's default security group is used.

subnet

Required *

object

Identifies a subnet by a unique property.

Response

201 - The bare metal server network interface was created successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and source IP spoofing is managed on the attached virtual network interface.

created_at

string

The date and time that the bare metal server network interface was created.

If this bare metal server has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the bare metal server network interface, allowing the workload to perform any needed NAT operations.
• `allow_ip_spoofing` must be `false`.
• `interface_type` must not be `hipersocket`.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and infrastructure NAT is managed on the attached virtual network interface.

floating_ips

array

The floating IPs associated with this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the floating IPs are associated with the attached virtual network interface.

href

string

The URL for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment.

id

string

The unique identifier for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the identifier is that of the corresponding network attachment.

interface_type

string

The interface type:

• `hipersocket`: a virtual device that provides high-speed TCP/IP connectivity within a `s390x` based system
• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI interface
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.
  • Has its own security groups and does not inherit those of the PCI device through which traffic flows.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the interface type is that of the corresponding network attachment.

The enumerated values for this property may expand in the future.

mac_address

string

The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be empty.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the MAC address is that of the attached virtual network interface.

name

string

The name for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the name matches its corresponding network attachment.

port_speed

integer

The bare metal server network interface port speed in Mbps.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the port speed is that of its corresponding network attachment.

primary_ip

object

The primary IP address of this bare metal server network interface.

resource_type

string

The resource type

security_groups

array

The security groups targeting this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the security groups are associated with the attached virtual network interface.

status

string

The status of the bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the status is computed from them.

subnet

object

The associated subnet

type

string

The bare metal server network interface type.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the type is that of its corresponding network attachment.

400 - An invalid bare metal server network interface prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The bare metal server network interface is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server network interface prototype object conflicts with another

network interface for the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a bare metal server network interface

DELETE /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}

This request deletes a bare metal server network interface. This operation cannot be reversed. Any floating IPs associated with the bare metal server network interface are implicitly disassociated. The primary bare metal server network interface is not allowed to be deleted.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and is not allowed to be deleted.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.delete
• is.bare-metal-server.network-interface.detach
• is.floating-ip.floating-ip.detach
• is.subnet.reserved-ip.detach
• is.security-group.security-group.detach
• is.subnet.reserved-ip.delete
• is.subnet.subnet.update

Request

Response

204 - The bare metal server network interface was deleted successfully.

403 - The bare metal server network interface is not allowed to be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a bare metal server network interface

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}

This request retrieves a single bare metal server network interface specified by the identifier in the URL.

If this bare metal server has network attachments, the retrieved network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.read

Request

Response

200 - The bare metal server network interface was retrieved successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and source IP spoofing is managed on the attached virtual network interface.

created_at

string

The date and time that the bare metal server network interface was created.

If this bare metal server has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the bare metal server network interface, allowing the workload to perform any needed NAT operations.
• `allow_ip_spoofing` must be `false`.
• `interface_type` must not be `hipersocket`.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and infrastructure NAT is managed on the attached virtual network interface.

floating_ips

array

The floating IPs associated with this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the floating IPs are associated with the attached virtual network interface.

href

string

The URL for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment.

id

string

The unique identifier for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the identifier is that of the corresponding network attachment.

interface_type

string

The interface type:

• `hipersocket`: a virtual device that provides high-speed TCP/IP connectivity within a `s390x` based system
• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI interface
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.
  • Has its own security groups and does not inherit those of the PCI device through which traffic flows.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the interface type is that of the corresponding network attachment.

The enumerated values for this property may expand in the future.

mac_address

string

The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be empty.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the MAC address is that of the attached virtual network interface.

name

string

The name for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the name matches its corresponding network attachment.

port_speed

integer

The bare metal server network interface port speed in Mbps.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the port speed is that of its corresponding network attachment.

primary_ip

object

The primary IP address of this bare metal server network interface.

resource_type

string

The resource type

security_groups

array

The security groups targeting this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the security groups are associated with the attached virtual network interface.

status

string

The status of the bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the status is computed from them.

subnet

object

The associated subnet

type

string

The bare metal server network interface type.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the type is that of its corresponding network attachment.

404 - A bare metal server network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a bare metal server network interface

PATCH /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}

This request updates a bare metal server network interface with the information provided in a bare metal server network interface patch object. The bare metal server network interface patch object is structured in the same way as a retrieved bare metal server network interface and needs to contain only the information to be updated.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and is not allowed to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.bare-metal-server.bare-metal-server.ip-spoofing
• is.bare-metal-server.bare-metal-server.infrastructure-nat

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.update

Request

Request Body

The bare metal server network interface patch

Response

200 - The bare metal server network interface was updated successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and source IP spoofing is managed on the attached virtual network interface.

created_at

string

The date and time that the bare metal server network interface was created.

If this bare metal server has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the bare metal server network interface, allowing the workload to perform any needed NAT operations.
• `allow_ip_spoofing` must be `false`.
• `interface_type` must not be `hipersocket`.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and infrastructure NAT is managed on the attached virtual network interface.

floating_ips

array

The floating IPs associated with this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the floating IPs are associated with the attached virtual network interface.

href

string

The URL for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment.

id

string

The unique identifier for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the identifier is that of the corresponding network attachment.

interface_type

string

The interface type:

• `hipersocket`: a virtual device that provides high-speed TCP/IP connectivity within a `s390x` based system
• `pci`: a physical PCI device which can only be created or deleted when the bare metal server is stopped
  • Has an `allowed_vlans` property which controls the VLANs that will be permitted to use the PCI interface
  • Cannot directly use an IEEE 802.1Q tag.
• `vlan`: a virtual device, used through a `pci` device that has the `vlan` in its array of `allowed_vlans`.
  • Must use an IEEE 802.1Q tag.
  • Has its own security groups and does not inherit those of the PCI device through which traffic flows.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the interface type is that of the corresponding network attachment.

The enumerated values for this property may expand in the future.

mac_address

string

The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be empty.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the MAC address is that of the attached virtual network interface.

name

string

The name for this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the name matches its corresponding network attachment.

port_speed

integer

The bare metal server network interface port speed in Mbps.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the port speed is that of its corresponding network attachment.

primary_ip

object

The primary IP address of this bare metal server network interface.

resource_type

string

The resource type

security_groups

array

The security groups targeting this bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the security groups are associated with the attached virtual network interface.

status

string

The status of the bare metal server network interface.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the status is computed from them.

subnet

object

The associated subnet

type

string

The bare metal server network interface type.

If this bare metal server has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the type is that of its corresponding network attachment.

400 - An invalid bare metal server network interface patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The bare metal server network interface is not allowed to be updated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server network interface patch conflicts with another

network interface for the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List floating IPs associated with a bare metal server network interface

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips

This request lists floating IPs associated with a bare metal server network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read
• is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.floating-ip.read

Request

Response

200 - The associated floating IPs were retrieved successfully.

floating_ips

array

The floating IPs

404 - A bare metal server network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Disassociate a floating IP from a bare metal server network interface

DELETE /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}

This request disassociates the specified floating IP from the specified bare metal server network interface

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate
• is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.detach
• is.floating-ip.floating-ip.detach

Request

Response

204 - The floating IP was disassociated successfully.

400 - The specified floating IP could not be disassociated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The floating IP is not allowed to be disassociated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - The specified floating IP address is not associated with the bare metal server network

interface with the specified identifier

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve associated floating IP

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}

This request retrieves a specified floating IP if it is associated with the bare metal server network interface specified in the URL

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read
• is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.floating-ip.read

Request

Response

200 - The associated floating IP was retrieved successfully.

address

string

The globally unique IP address

authorized_cidr

object

The public address range authorized CIDR this floating IP is allocated from.

created_at

string

The date and time that the floating IP was created

crn

string

The CRN for this floating IP

href

string

The URL for this floating IP

id

string

The unique identifier for this floating IP

name

string

The name for this floating IP. The name is unique across all floating IPs in the region.

profile

object

The profile for this floating IP.

resource_group

object

The resource group for this floating IP

resource_type

string

The resource type

status

string

The status of the floating IP.

The enumerated values for this property may expand in the future.

target

FloatingIPTarget

The target of this floating IP

zone

object

The zone this floating IP resides in

404 - The floating IP address is not associated with a bare metal server network interface

with the specified identifier

errors

array

The errors that occurred.

trace

string

The unique error identifier

PUT /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}

This request associates the specified floating IP with the specified bare metal server network interface. If `enable_infrastructure_nat` is `false`, this adds the IP to any existing associations. If `enable_infrastructure_nat` is `true`, this replaces any existing association.

The existing floating IP must:

• be in the same `zone` as the bare metal server
• not be allocated from an `authorized_cidr`
• not be required by another resource, such as a public gateway

A request body is not required, and if provided, is ignored.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate
• is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.network-interface.attach
• is.floating-ip.floating-ip.attach

Request

Response

201 - The floating IP was successfully associated with the bare metal server network

interface.

address

string

The globally unique IP address

authorized_cidr

object

The public address range authorized CIDR this floating IP is allocated from.

created_at

string

The date and time that the floating IP was created

crn

string

The CRN for this floating IP

href

string

The URL for this floating IP

id

string

The unique identifier for this floating IP

name

string

The name for this floating IP. The name is unique across all floating IPs in the region.

profile

object

The profile for this floating IP.

resource_group

object

The resource group for this floating IP

resource_type

string

The resource type

status

string

The status of the floating IP.

The enumerated values for this property may expand in the future.

target

FloatingIPTarget

The target of this floating IP

zone

object

The zone this floating IP resides in

400 - The specified floating IP could not be associated with the specified bare metal server

network interface.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The floating IP is not allowed to be associated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - The specified bare metal server network interface or floating IP could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List the primary reserved IP for a bare metal server network interface

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/ips

This request lists the primary reserved IP for a bare metal server network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read
• is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.subnet.reserved-ip.read

Request

Response

200 - The reserved IPs were retrieved successfully.

first

object

A link to the first page of resources

ips

array

A page of reserved IPs bound to the bare metal server network interface

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A bare metal server network interface with the specified identifier could not be

found for the specified bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve the primary reserved IP

GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/ips/{id}

This request retrieves the primary reserved IP for a bare metal server network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read
• is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.subnet.reserved-ip.read

Request

Response

200 - The bound reserved IP was retrieved successfully.

address

object

The IP address.

If the address has not yet been selected, the value will be `0.0.0.0`.

This property may expand to support IPv6 addresses in the future.

auto_delete

boolean

Indicates whether this reserved IP member will be automatically deleted when either `target` is deleted, or the reserved IP is unbound.

created_at

string

The date and time that the reserved IP was created

href

string

The URL for this reserved IP

id

string

The unique identifier for this reserved IP

lifecycle_state

object

The lifecycle state of the reserved IP

name

string

The name for this reserved IP. The name is unique across all reserved IPs in a subnet.

owner

string

The owner of the reserved IP.

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

target

ReservedIPTarget

The target this reserved IP is bound to.

If absent, this reserved IP is provider-owned or unbound.

The resources supported by this property may expand in the future.

404 - The reserved IP address with the specified identifier could not be found

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /bare_metal_servers/{bare_metal_server_id}/storage_access

This request retrieves the storage access secret for a bare metal server.

The storage access secret is required to connect to the volume.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.storage-access-secret.read

Request

Response

200 - The storage access secret was retrieved successfully.

created_at

string

The date and time that the `storage_access` secret was created.

encrypted_secret

string

The storage access secret, encrypted using `public_key` and returned as a base64-encoded string.

This property will only be present when the `status` of the `storage_access` secret is `active`.

public_key

object

The public SSH key used to encrypt the `storage_access` secret.

rotated_at

string

The date and time that the `storage_access` secret was last rotated.

status

string

The status of the storage access secret:

• `active`: The storage access secret is active and in use.
• `updating`: The storage access secret is being updated due to a rotation request.

The enumerated values for this property may expand in the future.

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

POST /bare_metal_servers/{bare_metal_server_id}/storage_access/encrypted_secret/rotate

This request rotates the storage access secret for the bare metal server, generating a new encrypted secret that will be used for authenticating future volume connections.

The new secret will be encrypted using the specified public SSH key (if provided), or an existing key of type `rsa` associated with the bare metal server. The encrypted secret can be retrieved from the bare metal server's `storage_access` property.

This operation does not impact volumes that are already attached and connected to the bare metal server. Existing connections will continue to function with the previous secret. However, any new volume attachment connections established after the rotation must use the new secret to authenticate successfully.

• Storage access secret can be rotated at most once per hour.
• Storage access secret can only be rotated when the `status` of the storage access secret is `active`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.bare-metal-server.bare-metal-server.manage-storage-access-secret
• is.key.key.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.storage-access-secret.update

Request

Request Body

BareMetalServerRotateStorageAccessSecretPrototype

The storage access rotate secret prototype object

key

object

Identifies a key by a unique property.

Response

202 - The storage access secret was successfully rotated.

400 - An invalid key was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The storage access secret rotation is not allowed.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The storage access secret rotation conflicts with the current state of the bare

metal server.

• A public SSH key of type `rsa` is required.
• Previous storage access secret rotation was within the last hour.
• The storage access secret can only be rotated when the `status` of the storage access secret is `active`.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List volumes attachments on a bare metal server

GET /bare_metal_servers/{bare_metal_server_id}/volume_attachments

This request lists volume attachments on a bare metal server. A volume attachment connects a volume to a bare metal server. Each bare metal server may have many volume attachments but each volume attachment connects exactly one bare metal server to exactly one volume.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.volume-attachment.read

Request

Response

200 - The volume attachments were retrieved successfully.

volume_attachments

array

The volume attachments for this bare metal server.

400 - An invalid request was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a volume attachment on a bare metal server

POST /bare_metal_servers/{bare_metal_server_id}/volume_attachments

This request creates a new volume attachment from a volume attachment prototype object, connecting a volume to a bare metal server. For this request to succeed, the specified volume must not be busy. The prototype object is structured in the same way as a retrieved volume attachment, and contains the information necessary to create the new volume attachment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.volume.volume.operate
• is.volume.volume.create
• is.snapshot.snapshot.operate
• is.volume.volume.allow-remote-account-snapshot-restore
• is.volume.volume.manage-attachment-mode

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.volume-attachment.create

Request

Request Body

BareMetalServerVolumeAttachmentPrototype

The volume attachment prototype object

delete_volume_on_bare_metal_server_delete

boolean

Indicates whether deleting the bare metal server will also delete the attached volume.

This property must be `false` if the volume's `attachment_mode` is `multiple`.

name

string

The name for this volume attachment. The name must not be used by another volume attachment on the bare metal server. If unspecified, the name will be a hyphenated list of randomly-selected words.

volume

Required *

BareMetalServerVolumeAttachmentPrototypeVolume

An existing volume to attach to the bare metal server, or a prototype object for a new volume. The volume's profile must support the attachment protocol specified in `protocol`

Response

201 - The volume attachment was created successfully, attaching the specified volume to the

bare metal server.

bandwidth

integer

The maximum bandwidth (in megabits per second) for the volume when attached to this bare metal server.

created_at

string

The date and time that the volume attachment was created.

delete_volume_on_bare_metal_server_delete

boolean

Indicates whether deleting the bare metal server will also delete the attached volume.

This property must be `false` if the volume's `attachment_mode` is `multiple`.

device

BareMetalServerVolumeAttachmentDevice

The configuration for the volume as a device in the bare metal server operating system.

This property may be absent if the `status` of the volume attachment is not `available`.

href

string

The URL for this bare metal server volume attachment

id

string

The unique identifier for this bare metal volume attachment

name

string

The name for this volume attachment. The name is unique across all volume attachments on the instance or bare metal server.

status

string

The status of this volume attachment.

• `attaching`: volume attachment is being initialized and not yet usable
• `detaching`: volume attachment is being removed.
• `available`: volume attachment is usable, connection to the volume can be established from the server's operating system.
• `unusable`: volume attachment is unusable due to the underlying volume state

The enumerated values for this property may expand in the future.

status_reason

object

The reasons for the current `status` (if any).

type

string

The type of volume attachment.

The enumerated values for this property may expand in the future.

volume

object

The volume attached to the bare metal server.

This property will be absent if the volume has not yet been provisioned.

400 - An invalid volume attachment prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The volume attachment is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The volume attachment prototype object conflicts with another volume attachment

on the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a volume attachment

DELETE /bare_metal_servers/{bare_metal_server_id}/volume_attachments/{id}

This request deletes a volume attachment. This operation cannot be reversed, but a new volume attachment may subsequently be created for the volume. For this request to succeed, the volume must not be busy.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate
• is.volume.volume.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.volume-attachment.delete

Request

Response

202 - The volume attachment deletion request was accepted.

400 - The specified volume attachment cannot be deleted because its volume is busy.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The volume attachment is not allowed to be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A volume attachment with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The volume attachment cannot be deleted due to a conflict with the current state of the

bare metal server or volume attachment.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a volume attachment

GET /bare_metal_servers/{bare_metal_server_id}/volume_attachments/{id}

This request retrieves a single volume attachment specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.volume-attachment.read

Request

Response

200 - The volume attachment was retrieved successfully.

bandwidth

integer

The maximum bandwidth (in megabits per second) for the volume when attached to this bare metal server.

created_at

string

The date and time that the volume attachment was created.

delete_volume_on_bare_metal_server_delete

boolean

Indicates whether deleting the bare metal server will also delete the attached volume.

This property must be `false` if the volume's `attachment_mode` is `multiple`.

device

BareMetalServerVolumeAttachmentDevice

The configuration for the volume as a device in the bare metal server operating system.

This property may be absent if the `status` of the volume attachment is not `available`.

href

string

The URL for this bare metal server volume attachment

id

string

The unique identifier for this bare metal volume attachment

name

string

The name for this volume attachment. The name is unique across all volume attachments on the instance or bare metal server.

status

string

The status of this volume attachment.

• `attaching`: volume attachment is being initialized and not yet usable
• `detaching`: volume attachment is being removed.
• `available`: volume attachment is usable, connection to the volume can be established from the server's operating system.
• `unusable`: volume attachment is unusable due to the underlying volume state

The enumerated values for this property may expand in the future.

status_reason

object

The reasons for the current `status` (if any).

type

string

The type of volume attachment.

The enumerated values for this property may expand in the future.

volume

object

The volume attached to the bare metal server.

This property will be absent if the volume has not yet been provisioned.

404 - A volume attachment with the specified identifier could not be found for the specified

bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a volume attachment

PATCH /bare_metal_servers/{bare_metal_server_id}/volume_attachments/{id}

This request updates a volume attachment with the information provided in a volume attachment patch object. The volume attachment patch object is structured in the same way as a retrieved volume attachment and needs to contain only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.volume.volume.manage-deletion-policy

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.volume-attachment.update

Request

Request Body

The volume attachment patch

Response

200 - The volume attachment was updated successfully.

bandwidth

integer

The maximum bandwidth (in megabits per second) for the volume when attached to this bare metal server.

created_at

string

The date and time that the volume attachment was created.

delete_volume_on_bare_metal_server_delete

boolean

Indicates whether deleting the bare metal server will also delete the attached volume.

This property must be `false` if the volume's `attachment_mode` is `multiple`.

device

BareMetalServerVolumeAttachmentDevice

The configuration for the volume as a device in the bare metal server operating system.

This property may be absent if the `status` of the volume attachment is not `available`.

href

string

The URL for this bare metal server volume attachment

id

string

The unique identifier for this bare metal volume attachment

name

string

The name for this volume attachment. The name is unique across all volume attachments on the instance or bare metal server.

status

string

The status of this volume attachment.

• `attaching`: volume attachment is being initialized and not yet usable
• `detaching`: volume attachment is being removed.
• `available`: volume attachment is usable, connection to the volume can be established from the server's operating system.
• `unusable`: volume attachment is unusable due to the underlying volume state

The enumerated values for this property may expand in the future.

status_reason

object

The reasons for the current `status` (if any).

type

string

The type of volume attachment.

The enumerated values for this property may expand in the future.

volume

object

The volume attached to the bare metal server.

This property will be absent if the volume has not yet been provisioned.

400 - An invalid volume attachment patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The volume attachment is not allowed to be updated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A volume attachment with the specified identifier could not be found for the specified

bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The volume attachment patch conflicts with another volume attachment

on the bare metal server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a bare metal server

DELETE /bare_metal_servers/{id}

This request deletes a bare metal server. This operation cannot be reversed. Any floating IPs associated with the bare metal server network interfaces are implicitly disassociated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.delete
• is.volume.volume.delete

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.delete
• is.bare-metal-server.network-interface.delete
• is.bare-metal-server.network-interface.detach
• is.bare-metal-server.network-attachment.delete
• is.bare-metal-server.network-attachment.detach
• is.virtual-network-interface.virtual-network-interface.detach
• is.virtual-network-interface.virtual-network-interface.delete
• is.floating-ip.floating-ip.detach
• is.security-group.security-group.detach
• is.subnet.reserved-ip.detach
• is.subnet.reserved-ip.delete
• is.subnet.subnet.update
• ``

Request

Response

202 - The bare metal server deletion request was accepted.

403 - The bare metal server is not allowed to be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a bare metal server

GET /bare_metal_servers/{id}

This request retrieves a single bare metal server specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.read

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.read

Request

Response

200 - The bare metal server was retrieved successfully.

bandwidth

integer

The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces

boot_target

BareMetalServerBootTarget

The resource from which this bare metal server is booted.

The resources supported by this property may expand in the future.

cpu

BareMetalServerCPU

The bare metal server CPU configuration

created_at

string

The date and time that the bare metal server was created

crn

string

The CRN for this bare metal server

disks

array

The disks for this bare metal server, including any disks that are associated with the `boot_target`.

enable_secure_boot

boolean

Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.

firmware

BareMetalServerFirmware

Firmware information for the bare metal server

health_reasons

array

The reasons for the current server `health_state` (if any):

• `reservation_capacity_unavailable`: The reservation affinity pool has no available capacity.
• `reservation_deleted`: The reservation affinity pool has a deleted reservation.
• `reservation_expired`: The reservation affinity pool has an expired reservation.
• `reservation_failed`: The reservation affinity pool has a failed reservation.

See health status reasons for details. The enumerated values for this property may expand in the future.

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this bare metal server

id

string

The unique identifier for this bare metal server

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the bare metal server.

memory

integer

The amount of memory, truncated to whole gibibytes

metadata_service

BareMetalServerMetadataService

The metadata service configuration for the bare metal server

name

string

The name for this bare metal server. The name is unique across all bare metal servers in the region.

network_attachments

array

The network attachments for this bare metal server, including the primary network attachment.

network_interfaces

array

The network interfaces for this bare metal server, including the primary network interface.

If this bare metal server has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.

nvme_qualified_name

object

An NVMe Qualified Name (NQN). NQNs are unique identifiers used in NVMe over Fabrics (NVMe-oF) to identify NVMe subsystems and hosts.

primary_network_attachment

object

The primary network attachment for this bare metal server.

primary_network_interface

object

The primary network interface for this bare metal server.

If this bare metal server has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.

profile

object

The profile for this bare metal server

reservation

object

The reservation used by this bare metal server. If absent, no reservation is in use.

reservation_affinity

BareMetalServerReservationAffinity

resource_group

object

The resource group for this bare metal server

resource_type

string

The resource type

status

string

The status of this bare metal server:

• `deleting`: server is undergoing deletion
• `failed`: server is failed and not usable (see `status_reasons`)
• `maintenance`: server is undergoing maintenance (not usable)
• `pending`: server is being provisioned and not yet usable
• `reinitializing`: server is reinitializing and not yet usable
• `restarting`: server is restarting and not yet usable
• `running`: server is powered on
• `starting`: server is starting and not yet usable
• `stopped`: server is powered off

The enumerated values for this property may expand in the future.

status_reasons

array

The reasons for the current status (if any).

storage_access

object

The storage access secret required to connect to remote storage.

This property will be present if an SSH Key of type `rsa` was provided during server initialization, reinitialization, or `storage_access` secret rotation.

trusted_platform_module

BareMetalServerTrustedPlatformModule

volume_attachments

array

The volume attachments for this bare metal server.

This array will be empty if no volumes are attached to the bare metal server.

vpc

object

The VPC this bare metal server resides in

zone

object

The zone this bare metal server resides in

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

PATCH /bare_metal_servers/{id}

This request updates a bare metal server with the information in a provided patch. The bare metal server patch object is structured in the same way as a retrieved bare metal server and contains only the information to be updated.

For this request to succeed, the properties in the request must adhere to the `allowed_use` property of the disk referenced in the server's `boot_target`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.update
• is.reservation.reservation.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.update
• is.bare-metal-server.bare-metal-server.detach
• is.reservation.reservation.detach
• is.bare-metal-server.bare-metal-server.attach
• is.reservation.reservation.attach

Request

Request Body

The bare metal server patch

Response

200 - The bare metal server was updated successfully.

bandwidth

integer

The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces

boot_target

BareMetalServerBootTarget

The resource from which this bare metal server is booted.

The resources supported by this property may expand in the future.

cpu

BareMetalServerCPU

The bare metal server CPU configuration

created_at

string

The date and time that the bare metal server was created

crn

string

The CRN for this bare metal server

disks

array

The disks for this bare metal server, including any disks that are associated with the `boot_target`.

enable_secure_boot

boolean

Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.

firmware

BareMetalServerFirmware

Firmware information for the bare metal server

health_reasons

array

The reasons for the current server `health_state` (if any):

• `reservation_capacity_unavailable`: The reservation affinity pool has no available capacity.
• `reservation_deleted`: The reservation affinity pool has a deleted reservation.
• `reservation_expired`: The reservation affinity pool has an expired reservation.
• `reservation_failed`: The reservation affinity pool has a failed reservation.

See health status reasons for details. The enumerated values for this property may expand in the future.

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this bare metal server

id

string

The unique identifier for this bare metal server

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the bare metal server.

memory

integer

The amount of memory, truncated to whole gibibytes

metadata_service

BareMetalServerMetadataService

The metadata service configuration for the bare metal server

name

string

The name for this bare metal server. The name is unique across all bare metal servers in the region.

network_attachments

array

The network attachments for this bare metal server, including the primary network attachment.

network_interfaces

array

The network interfaces for this bare metal server, including the primary network interface.

If this bare metal server has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.

nvme_qualified_name

object

An NVMe Qualified Name (NQN). NQNs are unique identifiers used in NVMe over Fabrics (NVMe-oF) to identify NVMe subsystems and hosts.

primary_network_attachment

object

The primary network attachment for this bare metal server.

primary_network_interface

object

The primary network interface for this bare metal server.

If this bare metal server has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.

profile

object

The profile for this bare metal server

reservation

object

The reservation used by this bare metal server. If absent, no reservation is in use.

reservation_affinity

BareMetalServerReservationAffinity

resource_group

object

The resource group for this bare metal server

resource_type

string

The resource type

status

string

The status of this bare metal server:

• `deleting`: server is undergoing deletion
• `failed`: server is failed and not usable (see `status_reasons`)
• `maintenance`: server is undergoing maintenance (not usable)
• `pending`: server is being provisioned and not yet usable
• `reinitializing`: server is reinitializing and not yet usable
• `restarting`: server is restarting and not yet usable
• `running`: server is powered on
• `starting`: server is starting and not yet usable
• `stopped`: server is powered off

The enumerated values for this property may expand in the future.

status_reasons

array

The reasons for the current status (if any).

storage_access

object

The storage access secret required to connect to remote storage.

This property will be present if an SSH Key of type `rsa` was provided during server initialization, reinitialization, or `storage_access` secret rotation.

trusted_platform_module

BareMetalServerTrustedPlatformModule

volume_attachments

array

The volume attachments for this bare metal server.

This array will be empty if no volumes are attached to the bare metal server.

vpc

object

The VPC this bare metal server resides in

zone

object

The zone this bare metal server resides in

400 - An invalid bare metal server patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The bare metal server is not allowed to be updated.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server patch conflicts with another bare metal server in the region,

or the provided bare metal server patch object specified one or more of:

• A property that can only be changed while the bare metal server `status` is `stopped`
• A bare metal server profile that does not support the bare metal server configuration

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update firmware for a bare metal server

POST /bare_metal_servers/{id}/firmware/update

This request updates a bare metal server to the latest available firmware. The server must be stopped.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server-firmware.update
• is.bare-metal-server.bare-metal-server.operate
• ``

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server-firmware.update
• is.bare-metal-server.bare-metal-server.start

Request

Request Body

BareMetalServerFirmwareUpdateOptions

Parameters to control firmware update

auto_start

boolean

Indicates whether to automatically start the bare metal server after the firmware update is successfully completed.

Response

204 - The firmware update action will run immediately.

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server must be stopped to issue a firmware update.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve initialization configuration for a bare metal server

GET /bare_metal_servers/{id}/initialization

This request retrieves configuration used to initialize the bare metal server, such as the image used, SSH keys, and any configured usernames and passwords. These can subsequently be changed on the server and therefore may not be current.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.initialization.read

Request

Response

200 - The initialization configuration was retrieved successfully.

default_trusted_profile

object

The default trusted profile configuration specified at bare metal server initialization. If absent, no default trusted profile was specified.

image

object

The image the bare metal server was provisioned from

keys

array

The public SSH keys used at initialization.

user_accounts

array

The user accounts that are created at initialization. There can be multiple account types distinguished by the `resource_type` property.

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

PUT /bare_metal_servers/{id}/initialization

This request reinitializes a bare metal server with the specified image and SSH keys. The server must be stopped. Upon successful reinitialization, the bare metal server will be started automatically.

For this request to succeed, the properties of the server which would result from the reinitialization must adhere to the specified image's `allowed_use` property.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• iam-identity.profile.get
• iam-identity.profile.update
• iam-identity.profile.linkToResource
• is.bare-metal-server.bare-metal-server.update
• is.key.key.operate
• is.image.image.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.initialization.update

Request

Request Body

BareMetalServerInitializationReplacePrototype

The image and keys with which to reinitialize the bare metal server

default_trusted_profile

object

The default trusted profile to be used when initializing the bare metal server.

If unspecified, no default trusted profile will be made available.

auto_link

boolean

If set to `true`, the system will create a link to the specified `target` trusted profile during server creation. Regardless of whether a link is created by the system or manually using the IAM Identity service, it will be automatically deleted when the server is deleted.

target

Required *

object

Identifies a trusted profile by a unique property.

keys

Required *

array

The public SSH keys to install on the bare metal server. Keys will be made available to the bare metal server as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the default user.

For Windows images, at least one SSH key of type `rsa` must be specified. One of the provided keys is selected to encrypt the administrator password. SSH keys are optional for other images; however, if no keys are specified, the bare metal server will be inaccessible unless the selected image provides an alternative access mechanism.

To allow for remote block storage attachment, at least one key of type `rsa` must be specified. One of the provided keys is selected to encrypt the `storage_access` secret. If no keys are specified, the bare metal server will be unable to connect to remote block storage until either:

• the server is reinitialized with at least one key of type `rsa`
• the `storage_access` secret is rotated with a key of type `rsa`

user_data

string

The user data to make available when setting up the bare metal server.

Response

200 - The bare metal server was reinitialized.

default_trusted_profile

object

The default trusted profile configuration specified at bare metal server initialization. If absent, no default trusted profile was specified.

image

object

The image the bare metal server was provisioned from

keys

array

The public SSH keys used at initialization.

user_accounts

array

The user accounts that are created at initialization. There can be multiple account types distinguished by the `resource_type` property.

400 - An invalid request body was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server cannot be reinitialized in its current state, or one or more

of the following:

• The bare metal server is not stopped

errors

array

The errors that occurred.

trace

string

The unique error identifier

Restart a bare metal server

POST /bare_metal_servers/{id}/restart

This request immediately restarts a bare metal server. For this request to succeed, the server must have a `status` of `running`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.restart

Request

Response

204 - The restart action will run immediately.

400 - The restart action could not be run.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The action is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server cannot be restarted in its current state.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Start a bare metal server

POST /bare_metal_servers/{id}/start

This request starts a bare metal server. It will run immediately provided the server is stopped.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.start

Request

Response

204 - The start action will run immediately.

400 - The start action could not be run.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The action is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server must be stopped to issue a start action.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Stop a bare metal server

POST /bare_metal_servers/{id}/stop

This request stops a bare metal server. It will run immediately provided the server is running. Note: A soft stop may not complete as it relies on the operating system to perform the operation.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.bare-metal-server.bare-metal-server.operate

Auditing

Calling this method generates the following auditing event.

• is.bare-metal-server.bare-metal-server.stop

Request

Request Body

BareMetalServerStopOptions

Parameters to control the type of stop operation

type

Required *

string

The type of stop operation:

• `soft`: signal running operating system to quiesce and shutdown cleanly
• `hard`: immediately stop the server

Response

204 - The stop action will be run immediately.

400 - The stop action could not be run.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The action is not allowed to be created.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A bare metal server with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The bare metal server must not be stopped to issue a stop action.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List cluster network profiles

GET /cluster_network/profiles

This request lists cluster network profiles available in the region. A cluster network profile specifies the performance characteristics and capabilities for a cluster network.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The cluster network profiles were retrieved successfully

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

profiles

array

A page of cluster network profiles

total_count

integer

The total number of resources across all pages

Retrieve a cluster network profile

GET /cluster_network/profiles/{name}

This request retrieves a single cluster network profile specified by the name in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

name

Required *

string

The cluster network profile name

Query Parameters

Response

200 - The cluster network profile was retrieved successfully

family

object

The product family this cluster network profile belongs to.

The enumerated values for this property may expand in the future.

href

string

The URL for this cluster network profile

name

string

The globally unique name for this cluster network profile

resource_type

string

The resource type

supported_instance_profiles

ClusterNetworkProfileSupportedInstanceProfiles

The instance profiles that support this cluster network profile.

zones

ClusterNetworkProfileZones

Zones in this region that support this cluster network profile.

404 - A cluster network profile with the specified name could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List cluster networks

GET /cluster_networks

This request lists cluster networks in the region. A cluster network is a grouping of resources in a separate networking space for high performance computing and networking.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.cluster-network.list
• is.cluster-network.cluster-network.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

vpc.id

Filters the collection to cluster networks with a `vpc.id` property matching the specified id.

vpc.crn

string

Filters the collection to cluster networks with a `vpc.crn` property matching the specified CRN.

vpc.name

string

Filters the collection to cluster networks with a `vpc.name` property matching the specified name.

Response

200 - The clusters were retrieved successfully.

cluster_networks

array

A page of cluster networks

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

Create a cluster network

POST /cluster_networks

This request creates a new cluster network from a cluster network prototype object. The prototype object is structured in the same way as a retrieved cluster network, and contains the information necessary to create the new cluster network.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.cluster-network.create
• is.vpc.vpc.operate

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.create

Request

Request Body

ClusterNetworkPrototype

The cluster network prototype object

name

string

The name for this cluster network. The name must not be used by another cluster network in the region. Names starting with `ibm-` are reserved for provider-owned resources, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.

profile

Required *

object

Identifies an cluster network profile by a unique property.

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

subnet_prefixes

array

vpc

Required *

object

Identifies a VPC by a unique property.

zone

Required *

object

Identifies a zone by a unique property.

Response

201 - The cluster network was created successfully.

created_at

string

The date and time that the cluster network was created.

crn

string

The CRN for this cluster network

href

string

The URL for this cluster network

id

string

The unique identifier for this cluster network

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network

name

string

The name for this cluster network. The name must not be used by another cluster network in the region.

profile

object

The profile for this cluster network

resource_group

object

The resource group for this cluster network

resource_type

string

The resource type

subnet_prefixes

array

The IP address ranges available for subnets for this cluster network.

vpc

object

The VPC this cluster network resides in

zone

object

The zone this cluster network resides in

400 - An invalid cluster network prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network prototype object conflicts with another cluster network

in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /cluster_networks/{cluster_network_id}/interfaces

This request lists cluster network interfaces in the region. A cluster network interface is a logical abstraction of a cluster network interface in a subnet, and may be attached to a target resource.

The cluster network interfaces will be sorted by their `created_at` property values, with newest cluster network interfaces first. Cluster network interfaces with identical `created_at` property values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.interface.list

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.interface.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

Response

200 - The cluster network interfaces were retrieved successfully.

first

object

A link to the first page of resources

interfaces

array

A page of cluster network interfaces

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A cluster network with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a cluster network interface

POST /cluster_networks/{cluster_network_id}/interfaces

This request creates a new cluster network interface from a cluster network interface prototype object. The prototype object is structured in the same way as a retrieved cluster network interface, and contains the information necessary to create the new cluster network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.interface.create
• is.cluster-network.subnet.operate
• is.cluster-network.subnet.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.interface.attach
• is.cluster-network.interface.create
• is.cluster-network.subnet-reserved-ip.attach
• is.cluster-network.subnet-reserved-ip.create
• is.cluster-network.subnet.update

Request

Request Body

ClusterNetworkInterfacePrototype

The cluster network interface prototype object

name

string

The name for this cluster network interface. The name must not be used by another interface in the cluster network. Names beginning with `ibm-` are reserved for provider-owned resources, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.

primary_ip

object

The primary IP address to bind to the cluster network interface. May be either a cluster network subnet reserved IP identity, or a cluster network subnet reserved IP prototype object which will be used to create a new cluster network subnet reserved IP.

If a cluster network subnet reserved IP identity is provided, the specified cluster network subnet reserved IP must be unbound.

If a cluster network subnet reserved IP prototype object with an address is provided, the address must be available on the cluster network interface's cluster network subnet. If no address is specified, an available address on the cluster network subnet will be automatically selected and reserved.

subnet

ClusterNetworkInterfaceSubnetPrototype

Identifies a cluster network subnet by a unique property.

Response

201 - The cluster network interface was created successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this cluster network interface. If `false`, source IP spoofing is prevented on this cluster network interface. If `true`, source IP spoofing is allowed on this cluster network interface.

auto_delete

boolean

Indicates whether this cluster network interface will be automatically deleted when `target` is deleted

created_at

string

The date and time that the cluster network interface was created

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the virtual network interface, allowing the workload to perform any needed NAT operations.

href

string

The URL for this cluster network interface

id

string

The unique identifier for this cluster network interface

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network interface

mac_address

string

The MAC address of the cluster network interface. May be absent if `lifecycle_state` is `pending`.

name

string

The name for this cluster network interface. The name is unique across all interfaces in the cluster network.

primary_ip

object

The cluster network subnet reserved IP for this cluster network interface.

resource_type

string

The resource type

subnet

ClusterNetworkSubnetReference

target

ClusterNetworkInterfaceTarget

The target of this cluster network interface.

If absent, this cluster network interface is not attached to a target.

The resources supported by this property may expand in the future.

vpc

object

The VPC this cluster network interface resides in.

zone

object

The zone this cluster network interface resides in.

400 - An invalid cluster network interface prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network interface prototype object conflicts with another interface

in the cluster network or the specified cluster network subnet does not have any free addresses.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a cluster network interface

DELETE /cluster_networks/{cluster_network_id}/interfaces/{id}

This request deletes a cluster network interface. This operation cannot be reversed. For this request to succeed, the cluster network interface must not be required by another resource, such as a cluster network attachment for a virtual server instance.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.interface.delete

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.interface.delete
• is.cluster-network.interface.detach
• is.cluster-network.subnet.update
• is.cluster-network.subnet-reserved-ip.delete
• is.cluster-network.subnet-reserved-ip.detach

Request

Path Parameters

Query Parameters

Response

202 - The cluster network interface deletion request was accepted.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this cluster network interface. If `false`, source IP spoofing is prevented on this cluster network interface. If `true`, source IP spoofing is allowed on this cluster network interface.

auto_delete

boolean

Indicates whether this cluster network interface will be automatically deleted when `target` is deleted

created_at

string

The date and time that the cluster network interface was created

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the virtual network interface, allowing the workload to perform any needed NAT operations.

href

string

The URL for this cluster network interface

id

string

The unique identifier for this cluster network interface

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network interface

mac_address

string

The MAC address of the cluster network interface. May be absent if `lifecycle_state` is `pending`.

name

string

The name for this cluster network interface. The name is unique across all interfaces in the cluster network.

primary_ip

object

The cluster network subnet reserved IP for this cluster network interface.

resource_type

string

The resource type

subnet

ClusterNetworkSubnetReference

target

ClusterNetworkInterfaceTarget

The target of this cluster network interface.

If absent, this cluster network interface is not attached to a target.

The resources supported by this property may expand in the future.

vpc

object

The VPC this cluster network interface resides in.

zone

object

The zone this cluster network interface resides in.

404 - A cluster network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network interface is in use and cannot be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network interface.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a cluster network interface

GET /cluster_networks/{cluster_network_id}/interfaces/{id}

This request retrieves a single cluster network interface specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.interface.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.interface.read

Request

Response

200 - The cluster network interface was retrieved successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this cluster network interface. If `false`, source IP spoofing is prevented on this cluster network interface. If `true`, source IP spoofing is allowed on this cluster network interface.

auto_delete

boolean

Indicates whether this cluster network interface will be automatically deleted when `target` is deleted

created_at

string

The date and time that the cluster network interface was created

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the virtual network interface, allowing the workload to perform any needed NAT operations.

href

string

The URL for this cluster network interface

id

string

The unique identifier for this cluster network interface

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network interface

mac_address

string

The MAC address of the cluster network interface. May be absent if `lifecycle_state` is `pending`.

name

string

The name for this cluster network interface. The name is unique across all interfaces in the cluster network.

primary_ip

object

The cluster network subnet reserved IP for this cluster network interface.

resource_type

string

The resource type

subnet

ClusterNetworkSubnetReference

target

ClusterNetworkInterfaceTarget

The target of this cluster network interface.

If absent, this cluster network interface is not attached to a target.

The resources supported by this property may expand in the future.

vpc

object

The VPC this cluster network interface resides in.

zone

object

The zone this cluster network interface resides in.

404 - A cluster network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a cluster network interface

PATCH /cluster_networks/{cluster_network_id}/interfaces/{id}

This request updates a cluster network interface with the information provided in a cluster network interface patch object. The patch object is structured in the same way as a retrieved cluster network interface and needs to contain only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.interface.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.interface.update

Request

Request Body

The cluster network interface patch

Path Parameters

Query Parameters

Response

200 - The cluster network interface was updated successfully.

allow_ip_spoofing

boolean

Indicates whether source IP spoofing is allowed on this cluster network interface. If `false`, source IP spoofing is prevented on this cluster network interface. If `true`, source IP spoofing is allowed on this cluster network interface.

auto_delete

boolean

Indicates whether this cluster network interface will be automatically deleted when `target` is deleted

created_at

string

The date and time that the cluster network interface was created

enable_infrastructure_nat

boolean

If `true`:

• The VPC infrastructure performs any needed NAT operations.
• `floating_ips` must not have more than one floating IP.

If `false`:

• Packets are passed unchanged to/from the virtual network interface, allowing the workload to perform any needed NAT operations.

href

string

The URL for this cluster network interface

id

string

The unique identifier for this cluster network interface

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network interface

mac_address

string

The MAC address of the cluster network interface. May be absent if `lifecycle_state` is `pending`.

name

string

The name for this cluster network interface. The name is unique across all interfaces in the cluster network.

primary_ip

object

The cluster network subnet reserved IP for this cluster network interface.

resource_type

string

The resource type

subnet

ClusterNetworkSubnetReference

target

ClusterNetworkInterfaceTarget

The target of this cluster network interface.

If absent, this cluster network interface is not attached to a target.

The resources supported by this property may expand in the future.

vpc

object

The VPC this cluster network interface resides in.

zone

object

The zone this cluster network interface resides in.

400 - An invalid cluster network interface patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A cluster network interface with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network interface patch conflicts with another interface in

the cluster network.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network interface.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List cluster network subnets

GET /cluster_networks/{cluster_network_id}/subnets

This request lists cluster network subnets in the cluster network. A cluster network subnet provides network routing between other cluster network subnets within a cluster network.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.list

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

Response

200 - The cluster network subnets were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

subnets

array

A page of subnets for the cluster network

total_count

integer

The total number of resources across all pages

404 - A cluster network with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a cluster network subnet

POST /cluster_networks/{cluster_network_id}/subnets

This request creates a new cluster network subnet from a cluster network subnet prototype object. The prototype object is structured in the same way as a retrieved cluster network subnet, and contains the information necessary to create the new cluster network subnet.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.create

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.update
• is.cluster-network.subnet.create

Request

Request Body

ClusterNetworkSubnetPrototype

The cluster network subnet prototype object

ip_version

string

The IP version(s) to support for this cluster network subnet.

name

string

The name for this cluster network subnet. The name must not be used by another cluster network subnet in the cluster network. Names starting with `ibm-` are reserved for provider-owned resources, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.

Response

201 - The cluster network subnet was created successfully.

available_ipv4_address_count

integer

The number of IPv4 addresses in this cluster network subnet that are not in use, and have not been reserved by the user or the provider.

created_at

string

The date and time that the cluster network subnet was created

href

string

The URL for this cluster network subnet

id

string

The unique identifier for this cluster network subnet

ip_version

object

The IP version for this cluster network subnet.

The enumerated values for this property may expand in the future.

ipv4_cidr_block

string

The IPv4 range of this cluster network subnet, expressed in CIDR format

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetLifecycleState

The lifecycle state of the cluster network subnet

name

string

The name for this cluster network subnet. The name is unique across all cluster network subnets in the cluster network.

resource_type

string

The resource type

total_ipv4_address_count

integer

The total number of IPv4 addresses in this cluster network subnet.

Note: This is calculated as 2^{(32 - prefix length)}. For example, the prefix length `/24` gives:<br> 2^{(32 - 24)} = 2⁸ = 256 addresses.

400 - An invalid cluster network subnet prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet prototype object conflicts with another cluster network

subnet in the cluster network.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List cluster network subnet reserved IPs

GET /cluster_networks/{cluster_network_id}/subnets/{cluster_network_subnet_id}/reserved_ips

This request lists cluster network subnet reserved IPs in the cluster network.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet-reserved-ip.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

Response

200 - The cluster network subnet reserved IPs were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

reserved_ips

array

A page of reserved IPs for the cluster network subnet

total_count

integer

The total number of resources across all pages

404 - A cluster network subnet with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a cluster network subnet reserved IP

POST /cluster_networks/{cluster_network_id}/subnets/{cluster_network_subnet_id}/reserved_ips

This request creates a new cluster network subnet reserved IP from a cluster network subnet reserved IP prototype object. The prototype object is structured in the same way as a retrieved cluster network subnet reserved IP, and contains the information necessary to create the new cluster network subnet reserved IP.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet.update
• is.cluster-network.subnet-reserved-ip.create

Request

Request Body

ClusterNetworkSubnetReservedIPPrototype

The cluster network subnet reserved IP prototype object

address

string

The IP address to reserve, which must not already be reserved on the subnet.

If unspecified, an available address on the subnet will automatically be selected.

name

string

The name for this cluster network subnet reserved IP. The name must not be used by another reserved IP in the cluster network subnet. Names starting with `ibm-` are reserved for provider-owned resources, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.

Response

201 - The cluster network subnet reserved IP was created successfully.

address

object

The IP address.

If the address is pending allocation, the value will be `0.0.0.0`.

This property may expand to support IPv6 addresses in the future.

auto_delete

boolean

Indicates whether this cluster network subnet reserved IP member will be automatically deleted when either `target` is deleted, or the cluster network subnet reserved IP is unbound.

created_at

string

The date and time that the cluster network subnet reserved IP was created

href

string

The URL for this cluster network subnet reserved IP

id

string

The unique identifier for this cluster network subnet reserved IP

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetReservedIPLifecycleState

The lifecycle state of the cluster network subnet reserved IP

name

string

The name for this cluster network subnet reserved IP. The name is unique across all reserved IPs in a cluster network subnet.

owner

string

The owner of the cluster network subnet reserved IP

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

target

ClusterNetworkSubnetReservedIPTarget

The target this cluster network subnet reserved IP is bound to.

If absent, this cluster network subnet reserved IP is provider-owned or unbound.

400 - An invalid cluster network subnet reserved IP prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet reserved IP prototype object conflicts with another

reserved IP in the cluster network subnet, or the cluster network reserved IP cannot be created due to one or more of the following conflicts:

• the cluster network subnet has no available IP addresses
• the cluster network subnet reserved IP prototype object specifies an address that is already in use

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /cluster_networks/{cluster_network_id}/subnets/{cluster_network_subnet_id}/reserved_ips/{id}

This request deletes a cluster network subnet reserved IP. This operation cannot be reversed.

For this request to succeed, the reserved IP must be unbound. A provider-owned reserved IP is not allowed to be deleted.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet.update
• is.cluster-network.subnet-reserved-ip.delete

Request

Path Parameters

Query Parameters

Response

202 - The cluster network subnet reserved IP deletion request was accepted.

address

object

The IP address.

If the address is pending allocation, the value will be `0.0.0.0`.

This property may expand to support IPv6 addresses in the future.

auto_delete

boolean

Indicates whether this cluster network subnet reserved IP member will be automatically deleted when either `target` is deleted, or the cluster network subnet reserved IP is unbound.

created_at

string

The date and time that the cluster network subnet reserved IP was created

href

string

The URL for this cluster network subnet reserved IP

id

string

The unique identifier for this cluster network subnet reserved IP

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetReservedIPLifecycleState

The lifecycle state of the cluster network subnet reserved IP

name

string

The name for this cluster network subnet reserved IP. The name is unique across all reserved IPs in a cluster network subnet.

owner

string

The owner of the cluster network subnet reserved IP

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

target

ClusterNetworkSubnetReservedIPTarget

The target this cluster network subnet reserved IP is bound to.

If absent, this cluster network subnet reserved IP is provider-owned or unbound.

403 - The cluster network subnet reserved IP is not allowed to be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A cluster network subnet reserved IP with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet reserved IP is in use and cannot be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network subnet.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a cluster network subnet reserved IP

GET /cluster_networks/{cluster_network_id}/subnets/{cluster_network_subnet_id}/reserved_ips/{id}

This request retrieves a single cluster network subnet reserved IP specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet-reserved-ip.read

Request

Response

200 - The cluster network subnet reserved IP was retrieved successfully.

address

object

The IP address.

If the address is pending allocation, the value will be `0.0.0.0`.

This property may expand to support IPv6 addresses in the future.

auto_delete

boolean

Indicates whether this cluster network subnet reserved IP member will be automatically deleted when either `target` is deleted, or the cluster network subnet reserved IP is unbound.

created_at

string

The date and time that the cluster network subnet reserved IP was created

href

string

The URL for this cluster network subnet reserved IP

id

string

The unique identifier for this cluster network subnet reserved IP

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetReservedIPLifecycleState

The lifecycle state of the cluster network subnet reserved IP

name

string

The name for this cluster network subnet reserved IP. The name is unique across all reserved IPs in a cluster network subnet.

owner

string

The owner of the cluster network subnet reserved IP

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

target

ClusterNetworkSubnetReservedIPTarget

The target this cluster network subnet reserved IP is bound to.

If absent, this cluster network subnet reserved IP is provider-owned or unbound.

404 - A cluster network subnet reserved IP with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a cluster network subnet reserved IP

PATCH /cluster_networks/{cluster_network_id}/subnets/{cluster_network_subnet_id}/reserved_ips/{id}

This request updates a cluster network subnet reserved IP with the information provided in a cluster network subnet reserved IP patch object. The patch object is structured in the same way as a retrieved cluster network subnet reserved IP and needs to contain only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet-reserved-ip.update

Request

Request Body

The cluster network subnet reserved IP patch

Path Parameters

Query Parameters

Response

200 - The cluster network subnet reserved IP was updated successfully.

address

object

The IP address.

If the address is pending allocation, the value will be `0.0.0.0`.

This property may expand to support IPv6 addresses in the future.

auto_delete

boolean

Indicates whether this cluster network subnet reserved IP member will be automatically deleted when either `target` is deleted, or the cluster network subnet reserved IP is unbound.

created_at

string

The date and time that the cluster network subnet reserved IP was created

href

string

The URL for this cluster network subnet reserved IP

id

string

The unique identifier for this cluster network subnet reserved IP

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetReservedIPLifecycleState

The lifecycle state of the cluster network subnet reserved IP

name

string

The name for this cluster network subnet reserved IP. The name is unique across all reserved IPs in a cluster network subnet.

owner

string

The owner of the cluster network subnet reserved IP

The enumerated values for this property may expand in the future.

resource_type

string

The resource type

target

ClusterNetworkSubnetReservedIPTarget

The target this cluster network subnet reserved IP is bound to.

If absent, this cluster network subnet reserved IP is provider-owned or unbound.

400 - An invalid cluster network subnet reserved IP patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A cluster network subnet reserved IP with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet reserved IP patch conflicts with another reserved IP in

the cluster network subnet, or the patch specifies an `auto_delete` value that conflicts with the current binding state of the reserved IP.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network subnet.

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /cluster_networks/{cluster_network_id}/subnets/{id}

This request deletes a cluster network subnet. This operation cannot be reversed.

For this request to succeed, this cluster subnet must not be attached to a cluster network interface.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.delete

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.update
• is.cluster-network.subnet.delete

Request

Path Parameters

Query Parameters

Response

202 - The cluster network subnet deletion request was accepted.

available_ipv4_address_count

integer

The number of IPv4 addresses in this cluster network subnet that are not in use, and have not been reserved by the user or the provider.

created_at

string

The date and time that the cluster network subnet was created

href

string

The URL for this cluster network subnet

id

string

The unique identifier for this cluster network subnet

ip_version

object

The IP version for this cluster network subnet.

The enumerated values for this property may expand in the future.

ipv4_cidr_block

string

The IPv4 range of this cluster network subnet, expressed in CIDR format

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetLifecycleState

The lifecycle state of the cluster network subnet

name

string

The name for this cluster network subnet. The name is unique across all cluster network subnets in the cluster network.

resource_type

string

The resource type

total_ipv4_address_count

integer

The total number of IPv4 addresses in this cluster network subnet.

Note: This is calculated as 2^{(32 - prefix length)}. For example, the prefix length `/24` gives:<br> 2^{(32 - 24)} = 2⁸ = 256 addresses.

404 - A cluster network subnet with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet is in use and cannot be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network subnet.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a cluster network subnet

GET /cluster_networks/{cluster_network_id}/subnets/{id}

This request retrieves a single cluster network subnet specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet.read

Request

Response

200 - The cluster network subnet was retrieved successfully.

available_ipv4_address_count

integer

The number of IPv4 addresses in this cluster network subnet that are not in use, and have not been reserved by the user or the provider.

created_at

string

The date and time that the cluster network subnet was created

href

string

The URL for this cluster network subnet

id

string

The unique identifier for this cluster network subnet

ip_version

object

The IP version for this cluster network subnet.

The enumerated values for this property may expand in the future.

ipv4_cidr_block

string

The IPv4 range of this cluster network subnet, expressed in CIDR format

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetLifecycleState

The lifecycle state of the cluster network subnet

name

string

The name for this cluster network subnet. The name is unique across all cluster network subnets in the cluster network.

resource_type

string

The resource type

total_ipv4_address_count

integer

The total number of IPv4 addresses in this cluster network subnet.

Note: This is calculated as 2^{(32 - prefix length)}. For example, the prefix length `/24` gives:<br> 2^{(32 - 24)} = 2⁸ = 256 addresses.

404 - A cluster network subnet with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a cluster network subnet

PATCH /cluster_networks/{cluster_network_id}/subnets/{id}

This request updates a cluster network subnet with the information provided in a cluster network subnet patch object. The patch object is structured in the same way as a retrieved cluster network subnet and needs to contain only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.subnet.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.subnet.update

Request

Request Body

The cluster network subnet patch

Path Parameters

Query Parameters

Response

200 - The cluster network subnet was updated successfully.

available_ipv4_address_count

integer

The number of IPv4 addresses in this cluster network subnet that are not in use, and have not been reserved by the user or the provider.

created_at

string

The date and time that the cluster network subnet was created

href

string

The URL for this cluster network subnet

id

string

The unique identifier for this cluster network subnet

ip_version

object

The IP version for this cluster network subnet.

The enumerated values for this property may expand in the future.

ipv4_cidr_block

string

The IPv4 range of this cluster network subnet, expressed in CIDR format

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

ClusterNetworkSubnetLifecycleState

The lifecycle state of the cluster network subnet

name

string

The name for this cluster network subnet. The name is unique across all cluster network subnets in the cluster network.

resource_type

string

The resource type

total_ipv4_address_count

integer

The total number of IPv4 addresses in this cluster network subnet.

Note: This is calculated as 2^{(32 - prefix length)}. For example, the prefix length `/24` gives:<br> 2^{(32 - 24)} = 2⁸ = 256 addresses.

400 - An invalid cluster network subnet patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A cluster network subnet with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network subnet patch conflicts with another cluster network subnet

in the cluster network.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network subnet.

errors

array

The errors that occurred.

trace

string

The unique error identifier

DELETE /cluster_networks/{id}

This request deletes a cluster network. This operation cannot be reversed.

For this request to succeed, virtual server instances must not reside in this cluster network.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.cluster-network.delete

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.delete
• is.cluster-network.interface.delete
• is.cluster-network.subnet-reserved-ip.delete
• is.cluster-network.subnet.delete

Request

Path Parameters

Query Parameters

Response

202 - The cluster network deletion request was accepted.

created_at

string

The date and time that the cluster network was created.

crn

string

The CRN for this cluster network

href

string

The URL for this cluster network

id

string

The unique identifier for this cluster network

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network

name

string

The name for this cluster network. The name must not be used by another cluster network in the region.

profile

object

The profile for this cluster network

resource_group

object

The resource group for this cluster network

resource_type

string

The resource type

subnet_prefixes

array

The IP address ranges available for subnets for this cluster network.

vpc

object

The VPC this cluster network resides in

zone

object

The zone this cluster network resides in

404 - A cluster network with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network is in use and cannot be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a cluster network

GET /cluster_networks/{id}

This request retrieves a single cluster network specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.cluster-network.read

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.read

Request

Response

200 - The cluster network was retrieved successfully.

created_at

string

The date and time that the cluster network was created.

crn

string

The CRN for this cluster network

href

string

The URL for this cluster network

id

string

The unique identifier for this cluster network

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network

name

string

The name for this cluster network. The name must not be used by another cluster network in the region.

profile

object

The profile for this cluster network

resource_group

object

The resource group for this cluster network

resource_type

string

The resource type

subnet_prefixes

array

The IP address ranges available for subnets for this cluster network.

vpc

object

The VPC this cluster network resides in

zone

object

The zone this cluster network resides in

404 - A cluster network with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a cluster

PATCH /cluster_networks/{id}

This request updates a cluster network with the information provided in a cluster network patch object. The patch object is structured in the same way as a retrieved cluster network and needs to contain only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.cluster-network.cluster-network.update

Auditing

Calling this method generates the following auditing event.

• is.cluster-network.cluster-network.update

Request

Request Body

The cluster network patch

Path Parameters

Query Parameters

Response

200 - The cluster network was updated successfully.

created_at

string

The date and time that the cluster network was created.

crn

string

The CRN for this cluster network

href

string

The URL for this cluster network

id

string

The unique identifier for this cluster network

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the cluster network

name

string

The name for this cluster network. The name must not be used by another cluster network in the region.

profile

object

The profile for this cluster network

resource_group

object

The resource group for this cluster network

resource_type

string

The resource type

subnet_prefixes

array

The IP address ranges available for subnets for this cluster network.

vpc

object

The VPC this cluster network resides in

zone

object

The zone this cluster network resides in

400 - An invalid cluster network patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A cluster network with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The cluster network patch conflicts with another cluster network

in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the cluster

network.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List dedicated host groups

GET /dedicated_host/groups

This request lists dedicated host groups in the region. Each dedicated host must belong to exactly one group, which controls placement of instances. Dedicated host groups do not span zones.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host-group.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host-group.read

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

zone.name

string

Filters the collection to resources with a `zone.name` property matching the exact specified name.

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

Response

200 - The dedicated host groups were retrieved successfully.

first

object

A link to the first page of resources

groups

array

A page of dedicated host groups

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

Create a dedicated host group

POST /dedicated_host/groups

This request creates a new dedicated host group.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host-group.create

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host-group.create

Request

Request Body

DedicatedHostGroupPrototype

The dedicated host group prototype object

family

Required *

string

The dedicated host profile family for hosts in this group

name

string

The name for this dedicated host group. The name must not be used by another dedicated host group in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

zone

Required *

object

Identifies a zone by a unique property.

Response

201 - The dedicated host group was created successfully.

created_at

string

The date and time that the dedicated host group was created

crn

string

The CRN for this dedicated host group

dedicated_hosts

array

The dedicated hosts that are in this dedicated host group

family

string

The dedicated host profile family for hosts in this group

href

string

The URL for this dedicated host group

id

string

The unique identifier for this dedicated host group

name

string

The name for this dedicated host group. The name is unique across all dedicated host groups in the region.

resource_group

object

The resource group for this dedicated host group

resource_type

string

The resource type

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host group.

zone

object

The zone this dedicated host group resides in

400 - An invalid dedicated host group prototype object was provided

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host group prototype object conflicts with another dedicated host

group in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a dedicated host group

DELETE /dedicated_host/groups/{id}

This request deletes a dedicated host group.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host-group.delete

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host-group.delete

Request

Response

204 - The dedicated host group was deleted successfully.

404 - A dedicated host group with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a dedicated host group

GET /dedicated_host/groups/{id}

This request retrieves a single dedicated host group specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host-group.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host-group.read

Request

Response

200 - The dedicated host group was retrieved successfully.

created_at

string

The date and time that the dedicated host group was created

crn

string

The CRN for this dedicated host group

dedicated_hosts

array

The dedicated hosts that are in this dedicated host group

family

string

The dedicated host profile family for hosts in this group

href

string

The URL for this dedicated host group

id

string

The unique identifier for this dedicated host group

name

string

The name for this dedicated host group. The name is unique across all dedicated host groups in the region.

resource_group

object

The resource group for this dedicated host group

resource_type

string

The resource type

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host group.

zone

object

The zone this dedicated host group resides in

404 - A dedicated host group with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a dedicated host group

PATCH /dedicated_host/groups/{id}

This request updates a dedicated host group with the information in a provided dedicated host group patch. The dedicated host group patch object is structured in the same way as a retrieved dedicated host group and contains only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host-group.update

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host-group.update

Request

Request Body

The dedicated host group patch

Response

200 - The dedicated host group was updated successfully.

created_at

string

The date and time that the dedicated host group was created

crn

string

The CRN for this dedicated host group

dedicated_hosts

array

The dedicated hosts that are in this dedicated host group

family

string

The dedicated host profile family for hosts in this group

href

string

The URL for this dedicated host group

id

string

The unique identifier for this dedicated host group

name

string

The name for this dedicated host group. The name is unique across all dedicated host groups in the region.

resource_group

object

The resource group for this dedicated host group

resource_type

string

The resource type

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host group.

zone

object

The zone this dedicated host group resides in

400 - An invalid dedicated host group patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A dedicated host group with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host group patch conflicts with another dedicated host group

in the region, or the dedicated host group must be empty to change family

errors

array

The errors that occurred.

trace

string

The unique error identifier

List dedicated host profiles

GET /dedicated_host/profiles

This request lists provisionable dedicated host profiles in the region. A dedicated host profile specifies the hardware characteristics for a dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The dedicated host profiles were retrieved successfully

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

profiles

array

A page of dedicated host profiles

total_count

integer

The total number of resources across all pages

Retrieve a dedicated host profile

GET /dedicated_host/profiles/{name}

This request retrieves a single dedicated host profile specified by the name in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

Auditing

Calling this method generates the following auditing event.

Request

Path Parameters

name

Required *

string

The dedicated host profile name

Query Parameters

Response

200 - The dedicated host profile was retrieved successfully

disks

DedicatedHostProfileDisks

The disks for a dedicated host with this profile

family

string

The product family this dedicated host profile belongs to

The enumerated values for this property may expand in the future.

href

string

The URL for this dedicated host

memory

DedicatedHostProfileMemory

name

string

The globally unique name for this dedicated host profile

socket_count

DedicatedHostProfileSocket

status

string

The status of the dedicated host profile:

• `previous`: This dedicated host profile is an older revision, but remains provisionable and usable.
• `current`: This dedicated host profile is the latest revision.

Revisions are indicated by the generation of a dedicated host profile. Refer to the profile naming conventions for information on how generations are defined within a dedicated host profile.

The enumerated values for this property may expand in the future.

supported_instance_profiles

array

The instance profiles usable by instances placed on dedicated hosts with this profile.

vcpu_architecture

DedicatedHostProfileVCPUArchitecture

vcpu_count

DedicatedHostProfileVCPU

vcpu_manufacturer

DedicatedHostProfileVCPUManufacturer

404 - A dedicated host profile with the specified name could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

List dedicated hosts

GET /dedicated_hosts

This request lists dedicated hosts in the region.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.read

Request

Path Parameters

Query Parameters

dedicated_host_group.id

Filters the collection to dedicated hosts with a `group.id` property matching the specified identifier.

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

zone.name

string

Filters the collection to resources with a `zone.name` property matching the exact specified name.

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

Response

200 - The dedicated hosts were retrieved successfully.

dedicated_hosts

array

A page of dedicated hosts

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

Create a dedicated host

POST /dedicated_hosts

This request creates a new dedicated host.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.create
• is.dedicated-host.dedicated-host-group.create
• is.dedicated-host.dedicated-host-group.update

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.create
• is.dedicated-host.dedicated-host-group.create
• is.dedicated-host.dedicated-host-group.update

Request

Request Body

DedicatedHostPrototype

The dedicated host prototype object

instance_placement_enabled

boolean

If set to true, instances can be placed on this dedicated host

name

string

The name for this dedicated host. The name must not be used by another dedicated host in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.

profile

Required *

object

Identifies a dedicated host profile by a unique property

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

Response

201 - The dedicated host was created successfully.

available_memory

integer

The amount of memory in gibibytes that is currently available for instances

available_vcpu

object

The VCPU configuration

created_at

string

The date and time that the dedicated host was created

crn

string

The CRN for this dedicated host

disks

array

The disks for the dedicated host

group

object

The dedicated host group this dedicated host is in

href

string

The URL for this dedicated host

id

string

The unique identifier for this dedicated host

instance_placement_enabled

boolean

If set to true, instances can be placed on this dedicated host

instances

array

The instances that are allocated to this dedicated host.

lifecycle_state

object

The lifecycle state of the dedicated host.

memory

integer

The total amount of memory in gibibytes for this host

name

string

The name for this dedicated host. The name is unique across all dedicated hosts in the region.

numa

DedicatedHostNUMA

The dedicated host NUMA configuration

profile

object

The profile for this dedicated host.

provisionable

boolean

Indicates whether this dedicated host is available for instance creation

resource_group

object

The resource group for this dedicated host

resource_type

string

The resource type

socket_count

integer

The total number of sockets for this host

state

string

The administrative state of the dedicated host.

The enumerated values for this property may expand in the future.

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host.

vcpu

object

The VCPU configuration

zone

object

The zone this dedicated host resides in

400 - An invalid dedicated host prototype object was provided

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host prototype object conflicts with another dedicated host in the region,

or the dedicated host group family must match the specified host profile family

errors

array

The errors that occurred.

trace

string

The unique error identifier

List disks on a dedicated host

GET /dedicated_hosts/{dedicated_host_id}/disks

This request lists disks on a dedicated host. A disk is a physical device that is locally attached to the compute node. By default, the listed disks are sorted by their `created_at` property values, with the newest disk first.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.read

Request

Response

200 - The dedicated host disks were retrieved successfully.

disks

array

The disks for the dedicated host

404 - A dedicated host with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a dedicated host disk

GET /dedicated_hosts/{dedicated_host_id}/disks/{id}

This request retrieves a single dedicated host disk specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.read

Request

Response

200 - The dedicated host disk was retrieved successfully.

available

integer

The remaining space left for instance placement in GB (gigabytes)

created_at

string

The date and time that the disk was created

href

string

The URL for this disk

id

string

The unique identifier for this disk

instance_disks

array

The instance disks that are on this dedicated host disk

interface_type

string

The disk interface used for attaching the disk

lifecycle_state

object

The lifecycle state of this dedicated host disk

name

string

The name for this dedicated host disk. The name is unique across all disks on the dedicated host.

provisionable

boolean

Indicates whether this dedicated host disk is available for instance disk creation

resource_type

string

The resource type

size

integer

The size of the disk in GB (gigabytes)

supported_instance_interface_types

DedicatedHostDiskSupportedInstanceInterfaceTypes

The instance disk interfaces supported for this dedicated host disk.

The enumerated values for this property may expand in the future.

404 - A dedicated host disk with the specified identifier could not be found for the specified

dedicated host.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a dedicated host disk

PATCH /dedicated_hosts/{dedicated_host_id}/disks/{id}

This request updates the dedicated host disk with the information in a provided patch.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.update

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.update

Request

Request Body

The dedicated host disk patch

Response

200 - The dedicated host disk was updated successfully.

available

integer

The remaining space left for instance placement in GB (gigabytes)

created_at

string

The date and time that the disk was created

href

string

The URL for this disk

id

string

The unique identifier for this disk

instance_disks

array

The instance disks that are on this dedicated host disk

interface_type

string

The disk interface used for attaching the disk

lifecycle_state

object

The lifecycle state of this dedicated host disk

name

string

The name for this dedicated host disk. The name is unique across all disks on the dedicated host.

provisionable

boolean

Indicates whether this dedicated host disk is available for instance disk creation

resource_type

string

The resource type

size

integer

The size of the disk in GB (gigabytes)

supported_instance_interface_types

DedicatedHostDiskSupportedInstanceInterfaceTypes

The instance disk interfaces supported for this dedicated host disk.

The enumerated values for this property may expand in the future.

400 - An invalid dedicated host disk patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A dedicated host disk with the specified identifier could not be found for the specified

dedicated host.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host disk patch conflicts with another disk for the dedicated host.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a dedicated host

DELETE /dedicated_hosts/{id}

This request deletes a dedicated host. This operation cannot be reversed. For this request to succeed, `instances` must be empty and `instance_placement_enabled` must be `false`.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.delete

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.delete

Request

Response

204 - The dedicated host was deleted successfully.

404 - A dedicated host with the specified dedicated host group and dedicated host identifiers

could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host is in use and cannot be deleted.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a dedicated host

GET /dedicated_hosts/{id}

This request retrieves a single dedicated host specified by the identifiers in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.read

Request

Response

200 - The dedicated host was retrieved successfully.

available_memory

integer

The amount of memory in gibibytes that is currently available for instances

available_vcpu

object

The VCPU configuration

created_at

string

The date and time that the dedicated host was created

crn

string

The CRN for this dedicated host

disks

array

The disks for the dedicated host

group

object

The dedicated host group this dedicated host is in

href

string

The URL for this dedicated host

id

string

The unique identifier for this dedicated host

instance_placement_enabled

boolean

If set to true, instances can be placed on this dedicated host

instances

array

The instances that are allocated to this dedicated host.

lifecycle_state

object

The lifecycle state of the dedicated host.

memory

integer

The total amount of memory in gibibytes for this host

name

string

The name for this dedicated host. The name is unique across all dedicated hosts in the region.

numa

DedicatedHostNUMA

The dedicated host NUMA configuration

profile

object

The profile for this dedicated host.

provisionable

boolean

Indicates whether this dedicated host is available for instance creation

resource_group

object

The resource group for this dedicated host

resource_type

string

The resource type

socket_count

integer

The total number of sockets for this host

state

string

The administrative state of the dedicated host.

The enumerated values for this property may expand in the future.

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host.

vcpu

object

The VCPU configuration

zone

object

The zone this dedicated host resides in

404 - A dedicated host with the specified dedicated host and group identifiers could not be

found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Update a dedicated host

PATCH /dedicated_hosts/{id}

This request updates a dedicated host with the information in a provided dedicated host patch. The dedicated host patch object is structured in the same way as a retrieved dedicated host and contains only the information to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dedicated-host.dedicated-host.update

Auditing

Calling this method generates the following auditing event.

• is.dedicated-host.dedicated-host.update

Request

Request Body

The dedicated host patch

Response

200 - The dedicated host was updated successfully.

available_memory

integer

The amount of memory in gibibytes that is currently available for instances

available_vcpu

object

The VCPU configuration

created_at

string

The date and time that the dedicated host was created

crn

string

The CRN for this dedicated host

disks

array

The disks for the dedicated host

group

object

The dedicated host group this dedicated host is in

href

string

The URL for this dedicated host

id

string

The unique identifier for this dedicated host

instance_placement_enabled

boolean

If set to true, instances can be placed on this dedicated host

instances

array

The instances that are allocated to this dedicated host.

lifecycle_state

object

The lifecycle state of the dedicated host.

memory

integer

The total amount of memory in gibibytes for this host

name

string

The name for this dedicated host. The name is unique across all dedicated hosts in the region.

numa

DedicatedHostNUMA

The dedicated host NUMA configuration

profile

object

The profile for this dedicated host.

provisionable

boolean

Indicates whether this dedicated host is available for instance creation

resource_group

object

The resource group for this dedicated host

resource_type

string

The resource type

socket_count

integer

The total number of sockets for this host

state

string

The administrative state of the dedicated host.

The enumerated values for this property may expand in the future.

supported_instance_profiles

array

The instance profiles usable by instances placed on this dedicated host.

vcpu

object

The VCPU configuration

zone

object

The zone this dedicated host resides in

400 - An invalid dedicated host patch was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A dedicated host with the specified dedicated host group and dedicated host identifiers

could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dedicated host patch conflicts with another dedicated host in the region.

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /dynamic_route_servers

This request lists dynamic route servers in the region. A dynamic route server is a collection of members that learn routes from BGP peers, and allows policies to be configured for groups of peers.

The dynamic route servers will be sorted by their `created_at` property values, with newest dynamic route server first. Dynamic route servers with identical `created_at` property values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.dynamic-route-server.list
• is.dynamic-route-server.dynamic-route-server.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server.list

Request

Path Parameters

Query Parameters

name

string

Filters the collection to resources with a `name` property matching the exact specified name.

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

resource_group.id

Filters the collection to resources with a `resource_group.id` property matching the specified identifier.

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

Response

200 - The dynamic route servers were retrieved successfully.

dynamic_route_servers

array

A page of dynamic route servers

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

POST /dynamic_route_servers

This request creates a new dynamic route server from a dynamic route server prototype object.

The prototype object is structured in the same way as a retrieved dynamic route server, and contains the information necessary to create the new dynamic route server.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.dynamic-route-server.create
• is.vpc.vpc.operate
• is.subnet.subnet.operate
• is.virtual-network-interface.virtual-network-interface.operate
• is.virtual-network-interface.virtual-network-interface.create
• is.security-group.security-group.operate

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server.create
• is.dynamic-route-server.member.create
• is.dynamic-route-server.member.attach
• is.virtual-network-interface.virtual-network-interface.create
• is.virtual-network-interface.virtual-network-interface.attach

Request

Request Body

DynamicRouteServerPrototype

The dynamic route server prototype

local_asn

Required *

object

The local autonomous system number (ASN) used for this dynamic route server and its connections.

members

Required *

array

The members for a dynamic route server.

name

string

The name for this dynamic route server. The name must not be used by another dynamic route server in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.

resource_group

ResourceGroupIdentity

The resource group to use. If unspecified, the account's default resource group will be used.

Response

201 - The dynamic route server was created successfully.

created_at

string

The date and time that the dynamic route server was created.

crn

string

The CRN for this dynamic route server

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this resource:

• `ok`: No abnormal behavior detected
• `degraded`: Experiencing compromised performance, capacity, or connectivity
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` resource may also have this state.

href

string

The URL for this dynamic route server

id

object

The unique identifier for this dynamic route server

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server.

local_asn

integer

The local autonomous system number (ASN) used for this dynamic route server and its connections.

members

array

name

string

The name for this dynamic route server. The name is unique across all dynamic route servers in the region.

resource_group

object

The resource group for this dynamic route server

resource_type

string

The resource type

vpc

object

The VPC this dynamic route server resides in.

400 - An invalid dynamic route server prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dynamic route server prototype object conflicts with another dynamic route server

in the region, or a member prototype specifies an existing virtual network interface with one or more of:

• `allow_ip_spoofing` set to `true`
• `enable_infrastructure_nat` set to `false`
• `protocol_state_filtering_mode` set to `disabled`
• `ips` other than the `primary_ip` address
• `target` set to another resource
• a floating IP bound to it.

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /dynamic_route_servers/{dynamic_route_server_id}/members

This request lists the members for a dynamic route server. A member learns routes from all peers in the dynamic route server's peer groups. It learns routes by using its virtual network interface to establish a BGP session to each peer. The dynamic route server member uses the bound virtual network interface primary ip to establish BGP sessions with the configured peer group peers

The dynamic route server members will be sorted by their `created_at` property, with the newest member first. Members with identical `created_at` values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.member.read
• is.dynamic-route-server.member.list

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server.read
• is.dynamic-route-server.dynamic-route-server.list

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The response lists dynamic route members in a dynamic route server.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

members

array

A page of members for the dynamic route server

next

object

A link to the next page of resources. This property is present for all pages except the last page

total_count

integer

The total number of resources across all pages

404 - A dynamic route server or dynamic route server member with the specified identifier

could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a member in a dynamic route server

POST /dynamic_route_servers/{dynamic_route_server_id}/members

This request creates a new member and adds the member to the dynamic route server. The virtual network interface must currently be unbound.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.member.create
• is.virtual-network-interface.virtual-network-interface.operate
• is.subnet.subnet.operate
• is.virtual-network-interface.virtual-network-interface.create
• is.security-group.security-group.operate

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server-virtual_network_interface.attach
• is.virtual-network-interface.virtual-network-interface.attach
• is.dynamic-route-server.dynamic-route-server-member.create

Request

Request Body

DynamicRouteServerMemberPrototype

The dynamic route server member prototype

name

Required *

string

The name for this dynamic route server member. The name must not be used by another member in the dynamic route server. If unspecified, the name will be a hyphenated list of randomly-selected words.

virtual_network_interfaces

Required *

array

The virtual network interfaces to use for this dynamic route server member.

Response

201 - The dynamic route server member creation request was accepted.

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this dynamic route server member:

• `ok`: No abnormal behavior detected
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A member with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` member may also have this state.

href

string

The URL for this dynamic route server member

id

string

The unique identifier for this dynamic route server member

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server member.

name

string

The name for this dynamic route server member. The name is unique across all members in the dynamic route server.

resource_type

string

The resource type

virtual_network_interfaces

array

The virtual network interfaces for this dynamic route server member.

400 - The dynamic route server member prototype object specifies one or more of:

• An invalid dynamic route server member prototype object was provided.
• The dynamic route server peer group has reached its maximum number of members.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A dynamic route server or dynamic route server member with the specified identifier

could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dynamic route server member prototype object specifies one or more of:

• The specified virtual network interface is bound to another target.
• The specified virtual network interface is not in the same zone as the dynamic route server.
• The specified virtual network interface is not in the same account as the dynamic route server.
• The specified virtual network interface does not have an associated `security_group`.
• The specified virtual network interface must not have other `floating_ips` or secondary `reserved_ips` associated with it.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a dynamic route server member

DELETE /dynamic_route_servers/{dynamic_route_server_id}/members/{id}

This operation deletes the member from a dynamic route server.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.member.delete
• is.virtual-network-interface.virtual-network-interface.operate

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server-virtual_network_interface.detach
• is.virtual-network-interface.virtual-network-interface.detach

Request

Response

202 - The dynamic route server member deletion request was accepted.

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this dynamic route server member:

• `ok`: No abnormal behavior detected
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A member with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` member may also have this state.

href

string

The URL for this dynamic route server member

id

string

The unique identifier for this dynamic route server member

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server member.

name

string

The name for this dynamic route server member. The name is unique across all members in the dynamic route server.

resource_type

string

The resource type

virtual_network_interfaces

array

The virtual network interfaces for this dynamic route server member.

400 - The last dynamic route server member could not be deleted from the dynamic route

server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - The specified dynamic route server or dynamic route server member could not

be found, or the dynamic route server member is not part of the dynamic route server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a dynamic route server member

GET /dynamic_route_servers/{dynamic_route_server_id}/members/{id}

This request retrieves the specified member that is part of a dynamic route server specified in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.member.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.dynamic-route-server.read

Request

Response

200 - The dynamic route server member was retrieved successfully.

health_reasons

array

The reasons for the current `health_state` (if any).

health_state

string

The health of this dynamic route server member:

• `ok`: No abnormal behavior detected
• `faulted`: Completely unreachable, inoperative, or otherwise entirely incapacitated
• `inapplicable`: The health state does not apply because of the current lifecycle state. A member with a lifecycle state of `failed` or `deleting` will have a health state of `inapplicable`. A `pending` member may also have this state.

href

string

The URL for this dynamic route server member

id

string

The unique identifier for this dynamic route server member

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server member.

name

string

The name for this dynamic route server member. The name is unique across all members in the dynamic route server.

resource_type

string

The resource type

virtual_network_interfaces

array

The virtual network interfaces for this dynamic route server member.

404 - The bound virtual network interface with the specified identifier could not be found

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /dynamic_route_servers/{dynamic_route_server_id}/peer_groups

This request lists the peer groups for a dynamic route server. A peer group is a collection of peers grouped together for applying policies.

The peer groups will be sorted by their `created_at` property values, with the newest peer group first. Peer groups with identical `created_at` property values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group.list
• is.dynamic-route-server.peer-group.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group.list

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

sort

string

Sorts the returned collection by the specified property name in ascending order. A `-` may be prepended to the name to sort in descending order. For example, the value `-created_at` sorts the collection by the `created_at` property in descending order, and the value `name` sorts it by the `name` property in ascending order.

Response

200 - The dynamic route server peer groups were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

peer_groups

array

A page of peer groups for the dynamic route server

total_count

integer

The total number of resources across all pages

404 - The specified dynamic route server could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a peer group for a dynamic route server

POST /dynamic_route_servers/{dynamic_route_server_id}/peer_groups

This request creates a new dynamic route server peer group from a dynamic route server peer group prototype object. The prototype object is structured in the same way as a retrieved dynamic route server peer group, and contains the information necessary to create the new dynamic route server peer group.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group.create

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group.create
• is.dynamic-route-server.peer-group-peer.create

Request

Request Body

DynamicRouteServerPeerGroupPrototype

The dynamic route server peer group prototype object

health_monitor

Required *

DynamicRouteServerPeerGroupHealthMonitorPrototype

The health monitoring configuration to use for this dynamic route server peer group.

name

string

The name for this dynamic route server peer group. The name must not be used by another peer group for this dynamic route server. If unspecified, the name will be a hyphenated list of randomly-selected words.

peers

Required *

array

A collection of peers of the same type having a similar network topology grouped together to apply identical policies and maintain consistent behavior.

prefix_watcher

DynamicRouteServerPeerGroupPrefixWatcherPrototype

The prefix watcher configuration to use for monitoring BGP routes in this peer group.

A route is monitored only if:

• It matches at least one entry in `monitored_prefixes`, and
• It does not match any entry in `excluded_prefixes`.

For a route to match a monitored or excluded `prefix`, the route must:

• Be contained within the `prefix`
• Satisfy the `ge` and `le` prefix length constraints:
  • If `le` is non-zero: `ge <= route_prefix_length <= le`
  • If `le` is zero and `ge` is non-zero: `ge <= route_prefix_length`
  • If both `ge` and `le` are zero: No prefix length constraints are applied.

excluded_prefixes

array

The specific prefixes within the `monitored_prefixes` that will not be monitored.

If unspecified, no prefixes will be excluded from `monitored_prefixes`.

monitored_prefixes

array

The IP address prefixes for this prefix watcher to monitor.

If unspecified, no prefixes will be monitored.

roles

Required *

array

The roles to assign to peers in this dynamic route server peer group:

• `next_hop`: The peer will be able to serve as a next hop for routing traffic.
• `router`: The peer will be able to participate in route exchange and route filtering.

state

string

The administrative state to use for this dynamic route server peer group:

• `disabled`: The peer group will be disabled. The dynamic route server members will not establish a BGP session with peers in this peer group.
• `enabled`: The peer group will be enabled. The dynamic route server members will try to establish a BGP session with `enabled` peers in this peer group.

Response

201 - The dynamic route server peer group was created successfully.

created_at

string

The date and time that this dynamic route server peer group was created.

creator

array

The type of resource that created this dynamic route server peer group: - `dynamic_route_server`: dynamic router server created peer group. - `transit_gateway`: transit gateway created peer group.

The enumerated values for this property may expand in the future.

health_monitor

DynamicRouteServerPeerGroupHealthMonitor

The health monitoring configuration used for this dynamic route server peer group.

href

string

The URL for this dynamic route server peer group.

id

string

The ID for this dynamic route server peer group peer

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server peer group.

name

string

The name for this dynamic route server peer group.

peers

array

prefix_watcher

DynamicRouteServerPeerGroupPrefixWatcher

The prefix watcher configuration used for this dynamic route server peer group.

resource_type

string

The resource type

roles

array

The roles assigned to peers in this dynamic route server peer group:

• `next_hop`: The peer can serve as a next hop for routing traffic.
• `router`: The peer can participate in route exchange and route filtering.

The enumerated values for this property may expand in the future.

state

string

The administrative state used for the dynamic route server peer group:

• `disabled`: The peer group is disabled, and the dynamic route server members will not establish a BGP session with peers in this peer group.
• `enabled`: The peer group is enabled, and the dynamic route server members will try to establish a BGP session with peers in this peer group.

status

string

The aggregate session status of the peers in this dynamic route server peer group:

- `degraded`: One or more dynamic route server peer group peers
were unable to establish a session.
- `down`: All dynamic route server peer group peers were unable
to establish a session.
- `initializing`: The dynamic route server peer group is in the process of establishing
 sessions with its peers.
- `unknown`: The aggregate session status of the dynamic route server peer group
 peers could not be determined.
- `up`: All dynamic route server peer group peers have established
sessions and are operating normally.

status_reasons

array

The reasons for the current dynamic route server peer group connection status (if any).

400 - An invalid dynamic route server peer group prototype object was

provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - The specified dynamic route server could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dynamic route server peer group prototype object conflicts with another peer

group for the dynamic route server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

GET /dynamic_route_servers/{dynamic_route_server_id}/peer_groups/{dynamic_route_server_peer_group_id}/peers

This request lists the BGP peers in a dynamic route server peer group. For every peer, A BGP session is established between the peer and each member in the dynamic route server.

The peers in a peer group will be sorted by their `created_at` property value, with the newest peer first. Peers with identical `created_at` values will in turn be sorted by ascending `name` property values.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group-peer.list
• is.dynamic-route-server.peer-group-peer.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group-peer.list

Request

Path Parameters

Query Parameters

start

string

A server-provided token determining what resource to start the page on

limit

integer

The number of resources to return on a page

Response

200 - The dynamic route server peer group peers were retrieved successfully.

first

object

A link to the first page of resources

limit

integer

The maximum number of resources that can be returned by the request

next

object

A link to the next page of resources. This property is present for all pages except the last page

peers

array

total_count

integer

The total number of resources across all pages

404 - The specified dynamic route server peer group could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Create a peer in a dynamic route server peer group

POST /dynamic_route_servers/{dynamic_route_server_id}/peer_groups/{dynamic_route_server_peer_group_id}/peers

This request creates a new peer in a dynamic route server peer group from a dynamic route server peer group peer prototype object. The prototype object is structured in the same way as a retrieved dynamic route server peer group peer, and contains the information necessary to create the new peer. For this request to succeed, there must not already be another peer with the same `endpoint` in any peer group for this dynamic route server.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group-peer.create
• is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group-peer.create

Request

Request Body

DynamicRouteServerPeerGroupPeerPrototype

The dynamic route server peer group peer prototype

Response

201 - The dynamic route server peer group peer was created successfully.

created_at

string

The date and time that this dynamic route server peer group peer was created.

creator

string

The type of resource that created this peer: - `dynamic_route_server`: The peer was created by a dynamic router server. - `transit_gateway`: The peer was created by a transit gateway.

The enumerated values for this property may expand in the future.

href

string

The URL for this dynamic route server peer group peer.

id

string

The ID for this dynamic route server peer group peer

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server peer group peer.

name

string

The name for this dynamic route server peer group peer. The name must not be used by another peer in the peer group.

resource_type

string

The resource type

status

string

The status of this dynamic route server peer group peer connection:

• `down`: not operational.
• `up`: operating normally.

status_reasons

array

The status reasons for the dynamic route server peer group peer.

400 - An invalid dynamic route server peer group peer prototype object was provided.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The specified peer group does not have a `creator` value of `dynamic_route_server`.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - The specified dynamic route server peer group could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dynamic route server peer group peer prototype object conflicts with another peer

in a peer group for the dynamic route server.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Delete a dynamic route server peer group peer

DELETE /dynamic_route_servers/{dynamic_route_server_id}/peer_groups/{dynamic_route_server_peer_group_id}/peers/{id}

This request deletes a dynamic route server peer group peer. This operation cannot be reversed. All routes that were learned from the peer group peer will be removed. The last peer in a peer group cannot be deleted. To remove the last peer, the peer group has to be deleted.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group-peer.delete

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group-peer.delete

Request

Path Parameters

Query Parameters

Response

202 - The dynamic route server peer group peer deletion request was accepted.

created_at

string

The date and time that this dynamic route server peer group peer was created.

creator

string

The type of resource that created this peer: - `dynamic_route_server`: The peer was created by a dynamic router server. - `transit_gateway`: The peer was created by a transit gateway.

The enumerated values for this property may expand in the future.

href

string

The URL for this dynamic route server peer group peer.

id

string

The ID for this dynamic route server peer group peer

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server peer group peer.

name

string

The name for this dynamic route server peer group peer. The name must not be used by another peer in the peer group.

resource_type

string

The resource type

status

string

The status of this dynamic route server peer group peer connection:

• `down`: not operational.
• `up`: operating normally.

status_reasons

array

The status reasons for the dynamic route server peer group peer.

400 - The dynamic route server peer group peer deletion object specifies one or

more of:

• The dynamic route server peer group `creator` is not `dynamic_route_server`.

errors

array

The errors that occurred.

trace

string

The unique error identifier

403 - The specified peer group does not have a `creator` value of `dynamic_route_server`.

errors

array

The errors that occurred.

trace

string

The unique error identifier

404 - A dynamic route server peer with the specified identifier could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

409 - The dynamic route server peer group peer deletion object specifies one or

more of:

• The dynamic route server peer group peer is the last peer in the peer group.

errors

array

The errors that occurred.

trace

string

The unique error identifier

412 - The provided `If-Match` value does not match the current ETag value of the dynamic

route server peer group peer.

errors

array

The errors that occurred.

trace

string

The unique error identifier

Retrieve a dynamic route server peer group peer

GET /dynamic_route_servers/{dynamic_route_server_id}/peer_groups/{dynamic_route_server_peer_group_id}/peers/{id}

This request retrieves a single dynamic route server peer group peer specified by the identifier in the URL.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group-peer.read

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group-peer.read

Request

Response

200 - The dynamic route server peer group peer was retrieved successfully.

created_at

string

The date and time that this dynamic route server peer group peer was created.

creator

string

The type of resource that created this peer: - `dynamic_route_server`: The peer was created by a dynamic router server. - `transit_gateway`: The peer was created by a transit gateway.

The enumerated values for this property may expand in the future.

href

string

The URL for this dynamic route server peer group peer.

id

string

The ID for this dynamic route server peer group peer

lifecycle_reasons

array

The reasons for the current `lifecycle_state` (if any).

lifecycle_state

object

The lifecycle state of the dynamic route server peer group peer.

name

string

The name for this dynamic route server peer group peer. The name must not be used by another peer in the peer group.

resource_type

string

The resource type

status

string

The status of this dynamic route server peer group peer connection:

• `down`: not operational.
• `up`: operating normally.

status_reasons

array

The status reasons for the dynamic route server peer group peer.

404 - A dynamic route server peer group peer with the specified identifier

could not be found.

errors

array

The errors that occurred.

trace

string

The unique error identifier

PATCH /dynamic_route_servers/{dynamic_route_server_id}/peer_groups/{dynamic_route_server_peer_group_id}/peers/{id}

This request updates a peer in a dynamic route server peer group with the information in a provided dynamic route server peer group peer patch. The patch object is structured in the same way as a retrieved dynamic route server peer group peer and contains only the information to be updated.

Only peers with a `creator` value of `dynamic_route_server` are allowed to be updated.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• is.dynamic-route-server.peer-group-peer.update

Auditing

Calling this method generates the following auditing event.

• is.dynamic-route-server.peer-group-peer.update