Introduction to the beta VPC API
This reference includes the full IBM Cloud® Virtual Private Cloud (VPC) API, as well as newly released, limited beta features for customer accounts with special approval to preview those features.
There are no backward-compatibility guarantees as a feature progresses through its beta phase, or from the final beta release to its initial GA release. Using features that are not GA mature could introduce the risk of corrupting resources in your account.
Read the introduction in the generally available Virtual Private Cloud API for details on endpoint URLs, authentication, auditing, error handling, versioning, and other important information.
Versioning
This reference documents beta API behavior for any date value in the version
parameter within 45
days of today’s date. To view the reference for any other supported versions of the API, select it
from the Version list. For more information, see
Versioning in the VPC API.
API requests must specify a version
query parameter date value within the last 45 days.
Maturity query parameter
API requests accept a maturity
query parameter. This parameter lets you decide on the level of
stability to use before features become generally available.
For the API behavior documented in this reference, beta API requests must specify a maturity=beta
query parameter. Omitting beta
results in the GA version of the API being used, which can result
in different behavior.
Example of using the maturity
parameter in a request:
curl -X GET "$vpc_api_endpoint/v1/snapshots?generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
Pagination
Some API requests can return many results. To improve performance, results are returned one page at a time, with a limited number of results on each page. The default page size is typically 50 items, with a maximum size of 100.
Before you make a beta
request that uses pagination, you must add the maturity
query parameter
to the href
value.
List the first five keys:
.../keys?limit=5&maturity=beta
List the first five keys on the next page:
../keys?limit=5&start=9d5a91a3e2cbd233b5a5b33436855ed1&maturity=beta
For more information, see Pagination in the VPC API reference.
Change log
Important changes to the beta API, such as additions, updates, and deprecations, are documented in the Beta VPC API change log.
Methods
List all VPCs
This request lists all VPCs in the region. A VPC is a virtual network that belongs to an account and provides logical isolation from other networks. A VPC is made up of resources in one or more zones. VPCs are regional, and each VPC can contain resources in multiple zones in a region.
GET /vpcs
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to VPCs with a
classic_access
property matching the specified value.Example:
true
curl -X GET "$vpc_api_endpoint/v1/vpcs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVpcsOptions := &vpcv1.ListVpcsOptions{} vpcs, response, err := vpcService.ListVpcs(listVpcsOptions)
ListVpcsOptions listVpcsOptions = new ListVpcsOptions.Builder() .classicAccess(true) .build(); Response<VPCCollection> response = service.listVpcs(listVpcsOptions).execute(); VPCCollection vpcCollection = response.getResult();
const response = await vpcService.listVpcs();
response = service.list_vpcs()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
Collection of VPCs
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The VPCs were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=20" }, "limit": 20, "next": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20" }, "total_count": 2, "vpcs": [ { "classic_access": false, "created_at": "2019-01-27T14:39:40Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "default_network_acl": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "id": "r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "name": "my-network-acl" }, "default_routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "default_security_group": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" }, "dns": { "enable_hub": false, "resolution_binding_count": 0, "resolver": { "configuration": "default", "servers": [ { "address": "161.26.0.10" }, { "address": "161.26.0.11" } ], "type": "system" } }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "vpc", "status": "available" }, { "classic_access": false, "created_at": "2019-01-27T15:40:41Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-5ea1da83-7b29-4fd2-912a-501a1b508b7c", "default_network_acl": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-699c2624-29f3-4edf-b29c-4193ce52cfad", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-699c2624-29f3-4edf-b29c-4193ce52cfad", "id": "r006-699c2624-29f3-4edf-b29c-4193ce52cfad", "name": "my-network-acl" }, "default_routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-5ea1da83-7b29-4fd2-912a-501a1b508b7c/routing_tables/r006-cdc00ecf-0886-4ae0-82ef-b64c06a4856b", "id": "r006-cdc00ecf-0886-4ae0-82ef-b64c06a4856b", "name": "my-routing-table", "resource_type": "routing_table" }, "default_security_group": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-35e4a234-12d5-4446-a8f9-96eb8cb763bb", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-35e4a234-12d5-4446-a8f9-96eb8cb763bb", "id": "r006-35e4a234-12d5-4446-a8f9-96eb8cb763bb", "name": "my-security-group" }, "dns": { "enable_hub": false, "resolution_binding_count": 0, "resolver": { "configuration": "default", "servers": [ { "address": "161.26.0.10" }, { "address": "161.26.0.11" } ], "type": "system" } }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-5ea1da83-7b29-4fd2-912a-501a1b508b7c", "id": "r006-5ea1da83-7b29-4fd2-912a-501a1b508b7c", "name": "my-vpc-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "vpc", "status": "available" } ] }
Create a VPC
This request creates a new VPC from a VPC prototype object. The prototype object is structured in the same way as a retrieved VPC, and contains the information necessary to create the new VPC.
POST /vpcs
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPC prototype object
Indicates whether a default address prefix will be automatically created for each zone in this VPC. If
manual
, this VPC will be created with no default address prefixes.Since address prefixes are managed identically regardless of whether they were automatically created, the value is not preserved as a VPC property.
Allowable values: [
auto
,manual
]Default:
auto
Example:
manual
Indicates whether this VPC will be connected to Classic Infrastructure. If true, this VPC's resources will have private network connectivity to the account's Classic Infrastructure resources. Only one VPC, per region, may be connected in this way. This value is set at creation and subsequently immutable.
Default:
false
The DNS configuration for this VPC.
If unspecified, the system will assign DNS servers capable of resolving hosts and endpoint gateways within this VPC, and hosts on the internet.
The name for this VPC. The name must not be used by another VPC in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpc
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/vpcs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-2" }'
options := &vpcv1.CreateVPCOptions{} options.SetResourceGroup(&vpcv1.ResourceGroupIdentity{ ID: &resourceGroup, }) options.SetName(name) vpc, response, err = vpcService.CreateVPC(options)
CreateVpcOptions createVpcOptions = new CreateVpcOptions.Builder() .name("my-vpc") .build(); Response<VPC> response = service.createVpc(createVpcOptions).execute(); VPC vpc = response.getResult();
const response = await vpcService.createVpc({ name: 'my-vpc' });
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id address_prefix_management = 'manual' classic_access = False name = 'my-vpc' resource_group = resource_group_identity_model response = service.create_vpc( address_prefix_management=address_prefix_management, classic_access=classic_access, name=name, resource_group=resource_group, )
Response
Indicates whether this VPC is connected to Classic Infrastructure. If true, this VPC's resources have private network connectivity to the account's Classic Infrastructure resources. Only one VPC, per region, may be connected in this way. This value is set at creation and subsequently immutable.
The date and time that the VPC was created
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The default network ACL to use for subnets created in this VPC.
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_network_acl
The default routing table to use for subnets created in this VPC.
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_routing_table
The default security group for this VPC. Resources created in this VPC that allow a security group to be optionally specified will use this security group by default.
Examples:ViewThe security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_security_group
The DNS configuration for this VPC.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource group for this VPC
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this VPC
Possible values: [
available
,deleting
,failed
,pending
]The CSE (Cloud Service Endpoint) source IP addresses for the VPC. The VPC will have one CSE source IP address per zone.
Status Code
The VPC was created successfully.
An invalid VPC prototype object was provided.
{ "classic_access": false, "created_at": "2019-01-27T14:39:40Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "default_network_acl": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "id": "r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "name": "my-network-acl" }, "default_routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "default_security_group": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" }, "dns": { "enable_hub": false, "resolution_binding_count": 0, "resolver": { "configuration": "default", "servers": [ { "address": "161.26.0.10" }, { "address": "161.26.0.11" } ], "type": "system" } }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "vpc", "status": "available" }
Delete a VPC
This request deletes a VPC. This operation cannot be reversed.
For this request to succeed:
- Instances, subnets, public gateways, endpoint gateways, and private path service gateways must not reside in this VPC
- The VPC must not be providing DNS resolution for any other VPCs
- If
dns.enable_hub
istrue
,dns.resolution_binding_count
must be zero
All security groups and network ACLs associated with the VPC are automatically deleted.
All flow log collectors with auto_delete
set to true
targeting the VPC or any
resource in the VPC are automatically deleted.
DELETE /vpcs/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.vpc.vpc.delete
is.flow-log-collector.flow-log-collector.delete
Generated when a flow log collector that had
auto_delete
set totrue
was attached to the VPCis.flow-log-collector.flow-log-collector.detach
Generated when a flow log collector was attached to the VPC
is.vpc.vpc.detach
Generated when the VPC had a flow log collector attached to it
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVpcOptions := &vpcv1.DeleteVPCOptions{} deleteVpcOptions.SetID(id) response, err := vpcService.DeleteVPC(deleteVpcOptions)
DeleteVpcOptions deleteVpcOptions = new DeleteVpcOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteVpc(deleteVpcOptions).execute();
const response = await vpcService.deleteVpc({ id });
response = service.delete_vpc(id)
Retrieve a VPC
This request retrieves a single VPC specified by the identifier in the URL.
GET /vpcs/{id}
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVpcOptions := &vpcv1.GetVPCOptions{} getVpcOptions.SetID(id) vpc, response, err := vpcService.GetVPC(getVpcOptions)
GetVpcOptions getVpcOptions = new GetVpcOptions.Builder() .id(id) .build(); Response<VPC> response = service.getVpc(getVpcOptions).execute(); VPC vpc = response.getResult();
const response = await vpcService.getVpc({ id });
response = service.get_vpc(id)
Response
Indicates whether this VPC is connected to Classic Infrastructure. If true, this VPC's resources have private network connectivity to the account's Classic Infrastructure resources. Only one VPC, per region, may be connected in this way. This value is set at creation and subsequently immutable.
The date and time that the VPC was created
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The default network ACL to use for subnets created in this VPC.
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_network_acl
The default routing table to use for subnets created in this VPC.
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_routing_table
The default security group for this VPC. Resources created in this VPC that allow a security group to be optionally specified will use this security group by default.
Examples:ViewThe security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_security_group
The DNS configuration for this VPC.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource group for this VPC
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this VPC
Possible values: [
available
,deleting
,failed
,pending
]The CSE (Cloud Service Endpoint) source IP addresses for the VPC. The VPC will have one CSE source IP address per zone.
Status Code
The VPC was retrieved successfully.
A VPC with the specified identifier could not be found.
{ "classic_access": false, "created_at": "2019-01-27T14:39:40Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "default_network_acl": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "id": "r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "name": "my-network-acl" }, "default_routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "default_security_group": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" }, "dns": { "enable_hub": false, "resolution_binding_count": 0, "resolver": { "configuration": "default", "servers": [ { "address": "161.26.0.10" }, { "address": "161.26.0.11" } ], "type": "system" } }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "vpc", "status": "available" }
Update a VPC
This request updates a VPC with the information provided in a VPC patch object. The patch object is structured in the same way as a retrieved VPC and needs to contain only the information to be updated.
PATCH /vpcs/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPC patch
The DNS configuration for this VPC.
The name for this VPC. The name must not be used by another VPC in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpc
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-2-updated" }'
options := &vpcv1.UpdateVPCOptions{ Name: &name, } options.SetID(id) vpc, response, err := vpcService.UpdateVPC(options)
UpdateVpcOptions updateVpcOptions = new UpdateVpcOptions.Builder() .id(id) .name(name) .build(); Response<VPC> response = service.updateVpc(updateVpcOptions).execute(); VPC vpc = response.getResult();
const response = await vpcService.updateVpc({ id, name: 'my-vpc' });
response = service.update_vpc( id, name='my-vpc', )
Response
Indicates whether this VPC is connected to Classic Infrastructure. If true, this VPC's resources have private network connectivity to the account's Classic Infrastructure resources. Only one VPC, per region, may be connected in this way. This value is set at creation and subsequently immutable.
The date and time that the VPC was created
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The default network ACL to use for subnets created in this VPC.
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_network_acl
The default routing table to use for subnets created in this VPC.
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_routing_table
The default security group for this VPC. Resources created in this VPC that allow a security group to be optionally specified will use this security group by default.
Examples:ViewThe security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_security_group
The DNS configuration for this VPC.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource group for this VPC
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this VPC
Possible values: [
available
,deleting
,failed
,pending
]The CSE (Cloud Service Endpoint) source IP addresses for the VPC. The VPC will have one CSE source IP address per zone.
Status Code
The VPC was updated successfully.
An invalid VPC patch was provided.
A VPC with the specified identifier could not be found.
The VPC patch object has one or more of:
dns.enable_hub
incompatible withdns.resolution_binding_count
dns.enable_hub
incompatible withallow_dns_resolution_binding
values for endpoint gateways residing in the VPCdns.resolver.type
incompatible withdns.resolver.servers
dns.resolver.type
incompatible withdns.resolver.vpc
The provided
If-Match
value does not match the current ETag value of the VPC.
{ "classic_access": false, "created_at": "2019-01-27T14:39:40Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "default_network_acl": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "id": "r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf", "name": "my-network-acl" }, "default_routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "r006-6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "default_security_group": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" }, "dns": { "enable_hub": false, "resolution_binding_count": 0, "resolver": { "configuration": "default", "servers": [ { "address": "161.26.0.10" }, { "address": "161.26.0.11" } ], "type": "system" } }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "vpc", "status": "available" }
Retrieve a VPC's default network ACL
This request retrieves the default network ACL for the VPC specified by the identifier in the URL. The default network ACL is applied to any new subnets in the VPC which do not specify a network ACL.
GET /vpcs/{id}/default_network_acl
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/default_network_acl?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVPCDefaultNetworkACLOptions{} options.SetID(id) defaultACL, response, err := vpcService.GetVPCDefaultNetworkACL(options)
GetVpcDefaultNetworkAclOptions getVpcDefaultNetworkAclOptions = new GetVpcDefaultNetworkAclOptions.Builder() .id(id) .build(); Response<DefaultNetworkACL> response = service.getVpcDefaultNetworkAcl(getVpcDefaultNetworkAclOptions).execute(); DefaultNetworkACL defaultNetworkAcl = response.getResult();
const response = await vpcService.getVpcDefaultNetworkAcl({ id });
response = service.get_vpc_default_network_acl(id)
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name of the default network ACL created for a VPC. The name will be a hyphenated list of randomly-selected words at creation, but may be changed.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mnemonic-ersatz-eatery-mythology
The resource group for the default network ACL for a VPC. Set to the VPC's resource group at creation.
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for the default network ACL for a VPC. Defaults to two rules which allow all inbound and outbound traffic, respectively. Rules for the default network ACL may be changed, added, or removed.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The default network ACL was retrieved successfully.
The specified VPC could not be found.
{ "created_at": "2019-01-29T06:26:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "mnemonic-ersatz-eatery-mythology", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
Retrieve a VPC's default routing table
This request retrieves the default routing table for the VPC specified by the identifier in the URL. The default routing table is associated with any subnets in the VPC which have not been explicitly associated with another routing table.
GET /vpcs/{id}/default_routing_table
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/default_routing_table?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetVPCDefaultRoutingTableOptions(vpcId) defaultRoutingTable, response, err := vpcService.GetVPCDefaultRoutingTable(options)
GetVpcDefaultRoutingTableOptions getVpcDefaultRoutingTableOptions = new GetVpcDefaultRoutingTableOptions.Builder() .id(vpcId) .build(); Response<DefaultRoutingTable> response = service.getVpcDefaultRoutingTable(getVpcDefaultRoutingTableOptions).execute(); DefaultRoutingTable defaultRoutingTable = response.getResult();
const response = await vpcService.getVpcDefaultRoutingTable({id});
default_routing_table = vpc_service.get_vpc_default_routing_table( id=vpcId).get_result()
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name of the default routing table created for this VPC. The name will be a hyphenated list of randomly-selected words at creation, but may be changed.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
milled-easy-equine-machines
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for the default routing table for this VPC. The table is created with no routes, but routes may be added, changed, or removed with a subsequent request.
The subnets to which this routing table is attached
Status Code
The default routing table was retrieved successfully.
The specified VPC could not be found.
{ "accept_routes_from": [], "advertise_routes_to": [ "direct_link", "transit_gateway" ], "created_at": "2019-01-03T17:36:24Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "id": "eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "is_default": false, "lifecycle_state": "stable", "name": "milled-easy-equine-machines", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" } ] }
Retrieve a VPC's default security group
This request retrieves the default security group for the VPC specified by the identifier in the URL. Resources created in this VPC that allow a security group to be optionally specified will use this security group by default.
GET /vpcs/{id}/default_security_group
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/default_security_group?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVPCDefaultSecurityGroupOptions{} options.SetID(id) defaultSG, response, err := vpcService.GetVPCDefaultSecurityGroup(options)
GetVpcDefaultSecurityGroupOptions getVpcDefaultSecurityGroupOptions = new GetVpcDefaultSecurityGroupOptions.Builder() .id(id) .build(); Response<DefaultSecurityGroup> response = service.getVpcDefaultSecurityGroup(getVpcDefaultSecurityGroupOptions).execute(); DefaultSecurityGroup defaultSecurityGroup = response.getResult();
const response = await vpcService.getVpcDefaultSecurityGroup({ id });
response = service.get_vpc_default_security_group(id)
Response
The date and time that this security group was created
The security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for the default security group for a VPC. The name will be a hyphenated list of randomly-selected words at creation, but may changed.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
observant-chip-emphatic-engraver
The resource group for this security group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The rules for the default security group for a VPC. Defaults to allowing all outbound traffic, and allowing all inbound traffic from other interfaces in the VPC's default security group. Rules for the default security group may be changed, added or removed.
rules
The targets for this security group.
targets
The VPC this security group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The default security group was retrieved successfully.
The specified VPC could not be found.
{ "created_at": "2018-12-07T17:52:13Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037", "id": "2d364f0a-a870-42c3-a554-000001099037", "name": "my-security-group-allow-ssh", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }, { "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173005", "id": "b597cff2-38e8-4e6e-999d-000002173005", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 } ], "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-network-interface", "resource_type": "network_interface" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/31cf397a-286a-4289-a7e7-92f177e7e491", "id": "31cf397a-286a-4289-a7e7-92f177e7e491", "name": "my-vpc-2", "resource_type": "vpc" } }
List all address prefixes for a VPC
This request lists all address pool prefixes for a VPC.
GET /vpcs/{vpc_id}/address_prefixes
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVpcAddressPrefixesOptions := &vpcv1.ListVPCAddressPrefixesOptions{} listVpcAddressPrefixesOptions.SetVPCID(vpcID) addressPrefixes, response, err := vpcService.ListVPCAddressPrefixes(listVpcAddressPrefixesOptions)
ListVpcAddressPrefixesOptions listVpcAddressPrefixesOptions = new ListVpcAddressPrefixesOptions.Builder() .vpcId(vpcId) .build(); Response<AddressPrefixCollection> response = service.listVpcAddressPrefixes(listVpcAddressPrefixesOptions).execute(); AddressPrefixCollection addressPrefixCollection = response.getResult();
const response = await vpcService.listVpcAddressPrefixes({ vpcId });
response = service.list_vpc_address_prefixes(vpc_id)
Response
Collection of address prefixes
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/a4e28308-8ee7-46ab-8108-9f881f22bdbf/address_prefixes?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/a4e28308-8ee7-46ab-8108-9f881f22bdbf/address_prefixes?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The address prefixes were retrieved successfully.
The specified VPC could not be found.
{ "address_prefixes": [ { "cidr": "10.1.0.0/16", "created_at": "2019-01-07T16:56:54Z", "has_subnets": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes/df760133-3513-47e7-b980-26cca666561b", "id": "df760133-3513-47e7-b980-26cca666561b", "is_default": true, "name": "my-vpc-address-prefix-1", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }, { "cidr": "10.1.0.0/16", "created_at": "2019-01-03T17:36:24Z", "has_subnets": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes/df760133-3513-47e7-b980-26cca666561b", "id": "df760133-3513-47e7-b980-26cca666561b", "is_default": true, "name": "my-vpc-address-prefix-2", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes?limit=50" }, "limit": 50, "total_count": 2 }
Create an address prefix for a VPC
This request creates a new prefix from a prefix prototype object. The prototype object is structured in the same way as a retrieved prefix, and contains the information necessary to create the new prefix.
POST /vpcs/{vpc_id}/address_prefixes
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The prefix prototype object
The IPv4 range of the address prefix, expressed in CIDR format. The range must not overlap with any existing address prefixes in the VPC or any of the following reserved address ranges:
127.0.0.0/8
(IPv4 loopback addresses)161.26.0.0/16
(IBM services)166.8.0.0/14
(Cloud Service Endpoints)169.254.0.0/16
(IPv4 link-local addresses)224.0.0.0/4
(IPv4 multicast addresses)
The prefix length of the address prefix's CIDR must be between
/9
(8,388,608 addresses) and/29
(8 addresses).Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
10.0.0.0/24
The zone this address prefix will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Indicates whether this will be the default address prefix for this zone in this VPC. If
true
, the VPC must not have a default address prefix for this zone.Default:
false
Example:
true
The name for this address prefix. The name must not be used by another address prefix for the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-address-prefix-1
curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-address-prefix-1", "cidr": "10.1.0.0/16", "zone": { "name": "us-south-1" } }'
options := &vpcv1.CreateVPCAddressPrefixOptions{} options.SetVPCID(vpcID) options.SetCidr(cidr) options.SetName(name) options.SetZone(&vpcv1.ZoneIdentity{ Name: &zoneName, }) addressPrefix, response, err := vpcService.CreateVPCAddressPrefix(options)
ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateVpcAddressPrefixOptions createVpcAddressPrefixOptions = new CreateVpcAddressPrefixOptions.Builder() .vpcId(vpcId) .cidr("10.0.0.0/24") .zone(zoneIdentityModel) .name("my-vpc-address-prefix") .build(); Response<AddressPrefix> response = service.createVpcAddressPrefix(createVpcAddressPrefixOptions).execute(); AddressPrefix addressPrefix = response.getResult();
const params = { vpcId, cidr: '10.0.0.0/24', zone: { name: zoneName }, name: 'my-vpc-address-prefix', }; const response = await vpcService.createVpcAddressPrefix(params);
zone_identity_model = {} zone_identity_model['name'] = zoneName cidr = '10.0.0.0/24' zone = zone_identity_model is_default = True name = 'my-address-prefix' response = service.create_vpc_address_prefix( vpc_id, cidr, zone, is_default=is_default, name=name, )
Response
The CIDR block for this prefix
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The date and time that the prefix was created
Indicates whether subnets exist with addresses from this prefix.
The URL for this address prefix
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/address_prefixes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this address prefix
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
Indicates whether this is the default prefix for this zone in this VPC. If a default prefix was automatically created when the VPC was created, the prefix is automatically named using a hyphenated list of randomly-selected words, but may be changed.
The name for this address prefix. The name must not be used by another address prefix for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-address-prefix-1
The zone this address prefix resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The prefix was created successfully.
An invalid prefix prototype object was provided.
The specified VPC could not be found.
The prefix prototype object conflicts with another prefix in the VPC.
{ "cidr": "10.1.0.0/16", "created_at": "2019-01-07T16:56:54Z", "has_subnets": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes/df760133-3513-47e7-b980-26cca666561b", "id": "df760133-3513-47e7-b980-26cca666561b", "is_default": false, "name": "my-vpc-address-prefix-1", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete an address prefix
This request deletes a prefix. This operation cannot be reversed. The request will fail if any subnets use addresses from this prefix.
DELETE /vpcs/{vpc_id}/address_prefixes/{id}
Request
Path Parameters
The VPC identifier
The prefix identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes/$address_prefix_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVpcAddressPrefixOptions := &vpcv1.DeleteVPCAddressPrefixOptions{} deleteVpcAddressPrefixOptions.SetVPCID(vpcID) deleteVpcAddressPrefixOptions.SetID(addressPrefixID) response, err := vpcService.DeleteVPCAddressPrefix(deleteVpcAddressPrefixOptions)
DeleteVpcAddressPrefixOptions deleteVpcAddressPrefixOptions = new DeleteVpcAddressPrefixOptions.Builder() .vpcId(vpcId) .id(id) .build(); Response<Void> response = service.deleteVpcAddressPrefix(deleteVpcAddressPrefixOptions).execute();
const response = await vpcService.deleteVpcAddressPrefix({ vpcId, id, });
response = service.delete_vpc_address_prefix(vpc_id, id)
Retrieve an address prefix
This request retrieves a single prefix specified by the identifier in the URL.
GET /vpcs/{vpc_id}/address_prefixes/{id}
Request
Path Parameters
The VPC identifier
The prefix identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes/$address_prefix_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVpcAddressPrefixOptions := &vpcv1.GetVPCAddressPrefixOptions{} getVpcAddressPrefixOptions.SetVPCID(vpcID) getVpcAddressPrefixOptions.SetID(addressPrefixID) addressPrefix, response, err := vpcService.GetVPCAddressPrefix(getVpcAddressPrefixOptions)
GetVpcAddressPrefixOptions getVpcAddressPrefixOptions = new GetVpcAddressPrefixOptions.Builder() .vpcId(vpcId) .id(id) .build(); Response<AddressPrefix> response = service.getVpcAddressPrefix(getVpcAddressPrefixOptions).execute(); AddressPrefix addressPrefix = response.getResult();
const response = await vpcService.getVpcAddressPrefix({ vpcId, id });
response = service.get_vpc_address_prefix(vpc_id, id)
Response
The CIDR block for this prefix
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The date and time that the prefix was created
Indicates whether subnets exist with addresses from this prefix.
The URL for this address prefix
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/address_prefixes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this address prefix
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
Indicates whether this is the default prefix for this zone in this VPC. If a default prefix was automatically created when the VPC was created, the prefix is automatically named using a hyphenated list of randomly-selected words, but may be changed.
The name for this address prefix. The name must not be used by another address prefix for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-address-prefix-1
The zone this address prefix resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The prefix was retrieved successfully.
A prefix with the specified identifier could not be found.
{ "cidr": "10.1.0.0/16", "created_at": "2019-01-07T16:56:54Z", "has_subnets": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes/df760133-3513-47e7-b980-26cca666561b", "id": "df760133-3513-47e7-b980-26cca666561b", "is_default": false, "name": "my-vpc-address-prefix-1", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update an address prefix
This request updates a prefix with the information in a provided prefix patch. The prefix patch object is structured in the same way as a retrieved prefix and contains only the information to be updated.
PATCH /vpcs/{vpc_id}/address_prefixes/{id}
Request
Path Parameters
The VPC identifier
The prefix identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The prefix patch
Indicates whether this is the default prefix for this zone in this VPC. Updating to true makes this prefix the default prefix for this zone in this VPC, provided the VPC currently has no default address prefix for this zone. Updating to false removes the default prefix for this zone in this VPC.
The name for this address prefix. The name must not be used by another address prefix for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-address-prefix-1
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes/$address_prefix_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-address-prefix-1-updated" }'
options := &vpcv1.UpdateVPCAddressPrefixOptions{} options.SetVPCID(vpcID) options.SetID(addressPrefixID) options.SetName(name) addressPrefix, response, err := vpcService.UpdateVPCAddressPrefix(options)
UpdateVpcAddressPrefixOptions updateVpcAddressPrefixOptions = new UpdateVpcAddressPrefixOptions.Builder() .vpcId(vpcId) .id(id) .name(name) .build(); Response<AddressPrefix> response = service.updateVpcAddressPrefix(updateVpcAddressPrefixOptions).execute(); AddressPrefix addressPrefix = response.getResult();
const response = await vpcService.updateVpcAddressPrefix({ vpcId, id, name: 'my-vpc-address-prefix', });
is_default = False name = 'my-address-prefix' response = service.update_vpc_address_prefix( vpc_id, id, is_default=is_default, name=name, )
Response
The CIDR block for this prefix
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The date and time that the prefix was created
Indicates whether subnets exist with addresses from this prefix.
The URL for this address prefix
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/address_prefixes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this address prefix
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
Indicates whether this is the default prefix for this zone in this VPC. If a default prefix was automatically created when the VPC was created, the prefix is automatically named using a hyphenated list of randomly-selected words, but may be changed.
The name for this address prefix. The name must not be used by another address prefix for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-address-prefix-1
The zone this address prefix resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The prefix was updated successfully.
An invalid prefix patch was provided.
A prefix with the specified identifier could not be found.
The prefix patch conflicts with another prefix in the VPC.
{ "cidr": "10.1.0.0/16", "created_at": "2019-01-07T16:56:54Z", "has_subnets": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f64efe74-a5a2-45c7-b37d-5071d2dd6339/address_prefixes/df760133-3513-47e7-b980-26cca666561b", "id": "df760133-3513-47e7-b980-26cca666561b", "is_default": false, "name": "my-vpc-address-prefix-1-updated", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all DNS resolution bindings for a VPC
This request lists all DNS resolution bindings for a VPC. A DNS resolution binding represents an association with another VPC for centralizing DNS name resolution.
If the VPC specified by the identifier in the URL is a DNS hub VPC (has dns.enable_hub
set to true
) then there is one binding for each VPC bound to the hub VPC. The endpoint
gateways in the bound VPCs can allow (using allow_dns_resolution_binding
) the hub
VPC to centralize resolution of their DNS names.
If the VPC specified by the identifier in the URL is not a DNS hub VPC, then there is at
most one binding (to a hub VPC). The endpoint gateways in the VPC specified by the
identifier in the URL can allow (using allow_dns_resolution_binding
) its hub VPC to
centralize resolution of their DNS names.
To make use of centralized DNS resolution, a VPC bound to a DNS hub VPC must
delegate DNS resolution to its hub VPC by setting dns.resolver.type
to delegate
.
The bindings will be sorted by their created_at
property values, with newest bindings
first. Bindings with identical created_at
property values will in turn be sorted by
ascending name
property values.
GET /vpcs/{vpc_id}/dns_resolution_bindings
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
Filters the collection to resources with a
vpc.remote.account.id
property matching the specified account identifier.Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVPCDnsResolutionBindingsOptions := &vpcv1.ListVPCDnsResolutionBindingsOptions{ } vpcdnsResolutionBindings, response, err := vpcService.ListVPCDnsResolutionBindings(listVPCDnsResolutionBindingsOptions)
ListVpcDnsResolutionBindingsOptions listVpcDnsResolutionBindingsOptions = new ListVpcDnsResolutionBindingsOptions.Builder() .vpcId(vpcId) .build(); Response<VPCDNSResolutionBindingCollection> response = service.listVpcDnsResolutionBindings(listVpcDnsResolutionBindingsOptions).execute();
const params = { vpc_id: data.vpcId, }; const response = await vpcService.listVpcDnsResolutionBindings(params);
response = vpc_service.list_vpc_dns_resolution_bindings( vpc_id=data['vpcID'], )
Response
Collection of DNS resolution bindings for this VPC.
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The DNS resolution bindings were retrieved successfully.
The specified VPC could not be found.
{ "dns_resolution_bindings": [ { "created_at": "2023-04-12T13:14:15Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-b73f9596-337b-44fe-a415-11cf243f225b", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-b73f9596-337b-44fe-a415-11cf243f225b", "id": "r006-b73f9596-337b-44fe-a415-11cf243f225b", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" }, { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "id": "r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "name": "my-endpoint-gateway-2", "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "id": "r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "lifecycle_state": "stable", "name": "my-dns-resolution-binding-1", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "id": "r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } }, { "created_at": "2023-04-12T14:15:16Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-east:a/bb1b52262f7441a586f49068482f1e60::endpoint-gateway:r006-5cdadb03-1d2b-4167-adc4-db8152f3d519", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-5cdadb03-1d2b-4167-adc4-db8152f3d519", "id": "r006-5cdadb03-1d2b-4167-adc4-db8152f3d519", "name": "my-endpoint-gateway-1", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-85405311-bc10-4876-a89e-2cd47f3604f1", "id": "r006-85405311-bc10-4876-a89e-2cd47f3604f1", "lifecycle_state": "stable", "name": "my-dns-resolution-binding-2", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "id": "r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings?limit=50" }, "limit": 50, "total_count": 2 }
Create a DNS resolution binding
This request creates a new DNS resolution binding from a DNS resolution binding prototype object. The prototype object is structured in the same way as a retrieved DNS resolution binding, and contains the information necessary to create the new DNS resolution binding.
For this request to succeed, dns.enable_hub
must be false
for the VPC specified by
the identifier in the URL, and the VPC must not already have a DNS resolution binding.
See About DNS sharing for VPE gateways for more information.
POST /vpcs/{vpc_id}/dns_resolution_bindings
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.vpc.vpc.update
Generated for the VPC specified by the identifier in the URL and for the VPC specified in the DNS resolution binding.
is.vpc.dns-resolution-binding.create
Generated for the VPC specified by the identifier in the URL.
is.vpc.dns-resolution-binding.connect
Generated for the VPC specified in the DNS resolution binding.
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The DNS resolution binding prototype object
Another VPC to bind this VPC to for DNS resolution. The VPC must have
dns.enable_hub
set totrue
, and may be in a different account (subject to IAM policies).Additionally, the VPC specified in the URL (this VPC) must have
dns.enable_hub
set tofalse
and adns.resolution_binding_count
of zero.The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The name for this DNS resolution binding. The name must not be used by another DNS resolution binding for the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding
curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "vpc": { "crn": "crn:v1:bluemix:public:is:us-east:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r014-865b1c91-32ec-43d6-afc1-edf0005765e8" }, "name": "my-dns-resolution-binding" }'
vpcIdentityModel := &vpcv1.VPCIdentityByID{ ID: &vpcID, } createVPCDnsResolutionBindingOptions := vpcService.NewCreateVPCDnsResolutionBindingOptions( vpcIdentityModel, ) createVPCDnsResolutionBindingOptions.Name = &[]string{"my-vpc-dns-resolution-binding"}[0] vpcdnsResolutionBinding, response, err := vpcService.CreateVPCDnsResolutionBinding(createVPCDnsResolutionBindingOptions)
VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(otherVpcId) .build(); CreateVpcDnsResolutionBindingOptions createVpcDnsResolutionBindingOptions = new CreateVpcDnsResolutionBindingOptions.Builder() .name("my-vpc-dns-resolution-binding") .vpcId(vpcId) .vpc(vpcIdentityModel) .build(); Response<VPCDNSResolutionBinding> response = vpcService.createVpcDnsResolutionBinding(createVpcDnsResolutionBindingOptions).execute(); VPCDNSResolutionBinding vpcdnsResolutionBinding = response.getResult();
const vpcIdentityModel = { id: data.otherVPCId, }; const params = { vpc_id: data.vpcId, vpc: vpcIdentityModel, name: 'my-vpc-dns-resolution-binding', }; const response = await vpcService.createVpcDnsResolutionBinding(params);
vpc_identity_model = { 'id': otherVPCId, } response = vpc_service.create_vpc_dns_resolution_binding( vpc_id=data['vpcID'], name='my-vpc-dns-resolution-binding' vpc=vpc_identity_model, )
Response
The date and time that the DNS resolution binding was created.
The endpoint gateways that have
allow_dns_resolution_binding
set totrue
and reside in the VPC that hasdns.enable_hub
set tofalse
.The endpoint gateways may be remote and therefore may not be directly retrievable.
Possible values: number of items ≥ 0, contains only unique items
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this DNS resolution binding
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings/r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The unique identifier for this DNS resolution binding
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The lifecycle state of the DNS resolution binding.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this DNS resolution binding. The name is unique across all DNS resolution bindings for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding
The resource type
Possible values: [
vpc_dns_resolution_binding
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The VPC bound to for DNS resolution.
The VPC may be remote and therefore may not be directly retrievable.
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
vpc
Status Code
The DNS resolution binding was created successfully.
An invalid DNS resolution binding prototype object was provided.
The DNS resolution binding prototype object specified a VPC that cannot create a binding in its current state, or the VPC specified in the URL cannot create a binding in its current state.
{ "created_at": "2023-04-12T13:14:15Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-b73f9596-337b-44fe-a415-11cf243f225b", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-b73f9596-337b-44fe-a415-11cf243f225b", "id": "r006-b73f9596-337b-44fe-a415-11cf243f225b", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" }, { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "id": "r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "name": "my-endpoint-gateway-2", "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "id": "r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "lifecycle_state": "stable", "name": "my-dns-resolution-binding-1", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "id": "r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } }
Delete a DNS resolution binding
This request deletes a DNS resolution binding. This operation cannot be reversed.
For this request to succeed, the VPC specified by the identifier in the URL must not have
dns.resolver.type
set to delegated
.
DELETE /vpcs/{vpc_id}/dns_resolution_bindings/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.vpc.vpc.update
Generated for the VPC specified by the identifier in the URL.
is.vpc.dns-resolution-binding.delete
Generated for the VPC specified by the identifier in the URL.
is.vpc.dns-resolution-binding.disconnect
Generated for the VPC specified by the identifier in the URL if
dns.enable_hub
istrue
, otherwise generated for the VPC specified in the DNS resolution binding.
Request
Path Parameters
The VPC identifier
The DNS resolution binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings/$dns_resolution_binding_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVPCDnsResolutionBindingOptions := vpcService.NewDeleteVPCDnsResolutionBindingOptions( vpcID, vpcdnsResolutionBindingID, ) response, err := vpcService.DeleteVPCDnsResolutionBinding(deleteVPCDnsResolutionBindingOptions)
DeleteVpcDnsResolutionBindingOptions deleteVpcDnsResolutionBindingOptions = new DeleteVpcDnsResolutionBindingOptions.Builder() .vpcId(vpcId) .id(vpcdnsResolutionBindingID) .build(); Response<Void> response = vpcService.deleteVpcDnsResolutionBinding(deleteVpcDnsResolutionBindingOptions).execute();
const params = { vpc_id: data.vpcId, id: data.vpcDnsResolutionBindingID, }; const response = await vpcService.deleteVpcDnsResolutionBinding(params);
response = vpc_service.delete_vpc_dns_resolution_binding( vpc_id=data['vpcID'], id=otherVPCId, )
Response
The date and time that the DNS resolution binding was created.
The endpoint gateways that have
allow_dns_resolution_binding
set totrue
and reside in the VPC that hasdns.enable_hub
set tofalse
.The endpoint gateways may be remote and therefore may not be directly retrievable.
Possible values: number of items ≥ 0, contains only unique items
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this DNS resolution binding
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings/r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The unique identifier for this DNS resolution binding
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The lifecycle state of the DNS resolution binding.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this DNS resolution binding. The name is unique across all DNS resolution bindings for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding
The resource type
Possible values: [
vpc_dns_resolution_binding
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The VPC bound to for DNS resolution.
The VPC may be remote and therefore may not be directly retrievable.
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
vpc
Status Code
The DNS resolution binding deletion request was accepted.
A DNS resolution binding with the specified identifier could not be found.
The DNS resolution binding is for a VPC that has delegated DNS resolution to the VPC specified in the DNS resolution binding.
{ "created_at": "2023-04-12T13:14:15Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-b73f9596-337b-44fe-a415-11cf243f225b", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-b73f9596-337b-44fe-a415-11cf243f225b", "id": "r006-b73f9596-337b-44fe-a415-11cf243f225b", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" }, { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "id": "r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "name": "my-endpoint-gateway-2", "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "id": "r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "lifecycle_state": "deleting", "name": "my-dns-resolution-binding-1", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "id": "r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } }
Retrieve a DNS resolution binding
This request retrieves a single DNS resolution binding specified by the identifier in the URL.
GET /vpcs/{vpc_id}/dns_resolution_bindings/{id}
Request
Path Parameters
The VPC identifier
The DNS resolution binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings/$dns_resolution_binding_id?version=2024-04-30&generation=2&maturity=beta"
getVPCDnsResolutionBindingOptions := vpcService.NewGetVPCDnsResolutionBindingOptions( vpcID, vpcdnsResolutionBindingID, ) vpcdnsResolutionBinding, response, err := vpcService.GetVPCDnsResolutionBinding(getVPCDnsResolutionBindingOptions)
GetVpcDnsResolutionBindingOptions getVpcDnsResolutionBindingOptions = new GetVpcDnsResolutionBindingOptions.Builder() .vpcId(vpcId) .id(vpcdnsResolutionBindingID) .build(); Response<VPCDNSResolutionBinding> response = vpcService.getVpcDnsResolutionBinding(getVpcDnsResolutionBindingOptions).execute(); VPCDNSResolutionBinding vpcdnsResolutionBinding = response.getResult();
const params = { vpc_id: data.vpcId, id: data.vpcDnsResolutionBindingID, }; const response = await vpcService.getVpcDnsResolutionBinding(params);
response = vpc_service.get_vpc_dns_resolution_binding( vpc_id=data['vpcID'], id=data['vpcDnsResolutionBindingID'], )
Response
The date and time that the DNS resolution binding was created.
The endpoint gateways that have
allow_dns_resolution_binding
set totrue
and reside in the VPC that hasdns.enable_hub
set tofalse
.The endpoint gateways may be remote and therefore may not be directly retrievable.
Possible values: number of items ≥ 0, contains only unique items
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this DNS resolution binding
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings/r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The unique identifier for this DNS resolution binding
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The lifecycle state of the DNS resolution binding.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this DNS resolution binding. The name is unique across all DNS resolution bindings for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding
The resource type
Possible values: [
vpc_dns_resolution_binding
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The VPC bound to for DNS resolution.
The VPC may be remote and therefore may not be directly retrievable.
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
vpc
Status Code
The DNS resolution binding was retrieved successfully.
A DNS resolution binding with the specified identifier could not be found.
{ "created_at": "2023-04-12T13:14:15Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-b73f9596-337b-44fe-a415-11cf243f225b", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-b73f9596-337b-44fe-a415-11cf243f225b", "id": "r006-b73f9596-337b-44fe-a415-11cf243f225b", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" }, { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "id": "r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "name": "my-endpoint-gateway-2", "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "id": "r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "lifecycle_state": "stable", "name": "my-dns-resolution-binding-1", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "id": "r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } }
Update a DNS resolution binding
This request updates a DNS resolution binding with the information in a provided DNS resolution binding patch. The DNS resolution binding patch object is structured in the same way as a retrieved DNS resolution binding and contains only the information to be updated.
PATCH /vpcs/{vpc_id}/dns_resolution_bindings/{id}
Request
Path Parameters
The VPC identifier
The DNS resolution binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The DNS resolution binding patch
The name for this DNS resolution binding. The name must not be used by another DNS resolution binding for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding-updated
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings/$dns_resolution_binding_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-dns-resolution-binding-updated" }'
updateVPCDnsResolutionBindingOptions := vpcService.NewUpdateVPCDnsResolutionBindingOptions( vpcID, vpcdnsResolutionBindingID, map[string]interface{}{"name": "my-vpc-dns-resolution-binding-updated"}, ) vpcdnsResolutionBinding, response, err := vpcService.UpdateVPCDnsResolutionBinding(updateVPCDnsResolutionBindingOptions)
VPCDNSResolutionBindingPatch vpcdnsResolutionBindingPatchModel = new VPCDNSResolutionBindingPatch.Builder() .name("my-vpc-dns-resolution-binding-updated") .build(); Map<String, Object> vpcdnsResolutionBindingPatchModelAsPatch = vpcdnsResolutionBindingPatchModel.asPatch(); UpdateVpcDnsResolutionBindingOptions updateVpcDnsResolutionBindingOptions = new UpdateVpcDnsResolutionBindingOptions.Builder() .vpcId(vpcId) .id(vpcdnsResolutionBindingID) .vpcdnsResolutionBindingPatch(vpcdnsResolutionBindingPatchModelAsPatch) .build(); Response<VPCDNSResolutionBinding> response = vpcService.updateVpcDnsResolutionBinding(updateVpcDnsResolutionBindingOptions).execute(); VPCDNSResolutionBinding vpcdnsResolutionBinding = response.getResult();
const params = { vpc_id: data.vpcId, id: data.vpcDnsResolutionBindingID, name: 'my-vpc-dns-resolution-binding-update', }; const response = await vpcService.updateVpcDnsResolutionBinding(params);
vpcdns_resolution_binding_patch_model = { } vpcdns_resolution_binding_patch_model['name']='my-vpc-dns-resolution-binding-updated' response = vpc_service.update_vpc_dns_resolution_binding( vpc_id=data['vpcID'], id=data['vpcDnsResolutionBindingID'], vpcdns_resolution_binding_patch=vpcdns_resolution_binding_patch_model, )
Response
The date and time that the DNS resolution binding was created.
The endpoint gateways that have
allow_dns_resolution_binding
set totrue
and reside in the VPC that hasdns.enable_hub
set tofalse
.The endpoint gateways may be remote and therefore may not be directly retrievable.
Possible values: number of items ≥ 0, contains only unique items
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this DNS resolution binding
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/dns_resolution_bindings/r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The unique identifier for this DNS resolution binding
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-8a524686-fcf6-4947-a59b-188c1ed78ad1
The lifecycle state of the DNS resolution binding.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this DNS resolution binding. The name is unique across all DNS resolution bindings for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dns-resolution-binding
The resource type
Possible values: [
vpc_dns_resolution_binding
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The VPC bound to for DNS resolution.
The VPC may be remote and therefore may not be directly retrievable.
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
vpc
Status Code
The DNS resolution binding was updated successfully.
An invalid DNS resolution binding patch was provided.
A DNS resolution binding with the specified identifier could not be found.
{ "created_at": "2023-04-12T13:14:15Z", "endpoint_gateways": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-b73f9596-337b-44fe-a415-11cf243f225b", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-b73f9596-337b-44fe-a415-11cf243f225b", "id": "r006-b73f9596-337b-44fe-a415-11cf243f225b", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" }, { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "id": "r006-277aebd8-a2b5-42a7-9ee6-f11e09552811", "name": "my-endpoint-gateway-2", "resource_type": "endpoint_gateway" } ], "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-86da44e7-e5e5-4492-a1c3-257a72a7ccee/dns_resolution_bindings/r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "id": "r006-a0d15ec5-a4a6-41ab-86e9-24a8d3dec435", "lifecycle_state": "stable", "name": "my-dns-resolution-binding-updated", "resource_type": "vpc_dns_resolution_binding", "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/bb1b52262f7441a586f49068482f1e60::vpc:r006-7b3eb370-cf87-45d1-824b-eee3df163a07", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "id": "r006-8a46f85d-4e60-4b74-abec-22d8a3487613", "name": "my-vpc", "remote": { "account": { "id": "bb1b52262f7441a586f49068482f1e60", "resource_type": "account" }, "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" } }, "resource_type": "vpc" } }
List all routes in a VPC's default routing table
This request lists all routes in the VPC's default routing table. Each route is
zone-specific and directs any packets matching its destination CIDR block to a next_hop
IP address. The most specific route matching a packet's destination will be used. If
multiple equally-specific routes exist, traffic will be distributed across them.
GET /vpcs/{vpc_id}/routes
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVPCRoutesOptions{} options.SetVPCID(vpcID) routes, response, err := vpcService.ListVPCRoutes(options)
ListVpcRoutesOptions listVpcRoutesOptions = new ListVpcRoutesOptions.Builder() .vpcId(vpcId) .build(); Response<RouteCollection> response = service.listVpcRoutes(listVpcRoutesOptions).execute(); RouteCollection routeCollection = response.getResult();
const response = await vpcService.listVpcRoutes({ vpcId });
response = service.list_vpc_routes(vpc_id, zone_name=zone_name)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/1a15dca5-7e33-45e1-b7c5-bc690e569531/routes?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of routes
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.
routes
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/1a15dca5-7e33-45e1-b7c5-bc690e569531/routes?start=a5e812a2-62c0-4555-86a5-907106760c56&limit=20
next
Status Code
The routes were retrieved successfully.
The specified VPC could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/ebdc5374-2050-4f9e-a357-27b5a1a664cf/routes?limit=50" }, "limit": 50, "routes": [ { "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }, { "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.0.2.5/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route-2", "next_hop": { "address": "192.0.2.6" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } } ], "total_count": 2 }
Create a route in a VPC's default routing table
This request creates a new route in the VPC's default routing table. The route prototype object is structured in the same way as a retrieved route, and contains the information necessary to create the new route. The request will fail if the new route will cause a loop.
POST /vpcs/{vpc_id}/routes
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The route prototype object
The destination CIDR of the route. The host identifier in the CIDR must be zero.
At most two routes per
zone
in a table can have the samedestination
andpriority
, and only if both routes have anaction
ofdeliver
and thenext_hop
is an IP address.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The zone to apply the route to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Allowable values: [
delegate
,delegate_vpc
,deliver
,drop
]Default:
deliver
Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.All routes in a routing table with the same
destination
andzone
must have the sameadvertise
value.Default:
false
The name for this route. The name must not be used by another route in the routing table. Names starting with
ibm-
are reserved for system-provided routes, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, it must be omitted or specified as0.0.0.0
.At most two routes per
zone
in a table can have the samedestination
andpriority
, and only when each route has anaction
ofdeliver
andnext_hop
is an IP address.next_hop
The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Default:
2
Example:
1
curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-route", "destination": "192.168.32.0/26", "next_hop": { "address": "192.168.64.9" }, "zone": "us-south-2" }'
options := &vpcv1.CreateVPCRouteOptions{} options.SetVPCID(vpcID) options.SetName(name) options.SetZone(&vpcv1.ZoneIdentity{ Name: &zoneName, }) options.SetNextHop(&vpcv1.RouteNextHopPrototype{ Address: &nextHopAddress, }) options.SetDestination(destination) route, response, err := vpcService.CreateVPCRoute(options)
RouteNextHopPrototypeRouteNextHopIP routeNextHopPrototypeModel = new RouteNextHopPrototypeRouteNextHopIP.Builder() .address("192.168.3.4") .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateVpcRouteOptions createVpcRouteOptions = new CreateVpcRouteOptions.Builder() .vpcId(vpcId) .nextHop(routeNextHopPrototypeModel) .destination("192.168.3.0/24") .zone(zoneIdentityModel) .name("my-vpc-route") .build(); Response<Route> response = service.createVpcRoute(createVpcRouteOptions).execute(); Route route = response.getResult();
const params = { vpcId, destination: '192.168.3.0/24', zone: { name: zoneName }, }; const response = await vpcService.createVpcRoute(params);
zone_identity_model = {} zone_identity_model['name'] = zoneName route_next_hop_prototype_model = {} route_next_hop_prototype_model['address'] = '192.168.3.4' destination = '10.168.10.0/24' zone = zone_identity_model name = 'my-route' next_hop = route_next_hop_prototype_model response = service.create_vpc_route( vpc_id, destination, zone, name=name, next_hop=next_hop, )
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
creator
Status Code
The route was created successfully.
An invalid route prototype object was provided.
The specified VPC could not be found.
The route prototype object conflicts with another route in the VPC.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Delete a VPC route
This request deletes a route. This operation cannot be reversed.
DELETE /vpcs/{vpc_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteVPCRouteOptions{} options.SetVPCID(vpcID) options.SetID(routeID) response, err := vpcService.DeleteVPCRoute(options)
DeleteVpcRouteOptions deleteVpcRouteOptions = new DeleteVpcRouteOptions.Builder() .vpcId(vpcId) .id(id) .build(); Response<Void> response = service.deleteVpcRoute(deleteVpcRouteOptions).execute();
const response = await vpcService.deleteVpcRoute({ vpcId, id });
response = service.delete_vpc_route(vpc_id, id)
Retrieve a VPC route
This request retrieves a single route specified by the identifier in the URL.
GET /vpcs/{vpc_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVPCRouteOptions{} options.SetVPCID(vpcID) options.SetID(routeID) route, response, err := vpcService.GetVPCRoute(options)
GetVpcRouteOptions getVpcRouteOptions = new GetVpcRouteOptions.Builder() .vpcId(vpcId) .id(id) .build(); Response<Route> response = service.getVpcRoute(getVpcRouteOptions).execute(); Route route = response.getResult();
const response = await vpcService.getVpcRoute({ vpcId, id });
response = service.get_vpc_route(vpc_id, id)
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
creator
Status Code
The route was retrieved successfully.
A route with the specified identifier could not be found.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Update a VPC route
This request updates a route with the information in a provided route patch. The route patch object is structured in the same way as a retrieved route and contains only the information to be updated.
PATCH /vpcs/{vpc_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The route patch
Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.Since all routes in a routing table with the same
destination
andzone
must have the sameadvertise
value, this property can only be changed for routes with a uniquedestination
andzone
in the routing table. For more information, see Advertising routes.The name for this route. The name must not be used by another route in the routing table. Names starting with
ibm-
are reserved for system-provided routes, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-route-2
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, specify0.0.0.0
or remove it by specifyingnull
.At most two routes per
zone
in a table can have the samedestination
andpriority
, and only when each route has anaction
ofdeliver
andnext_hop
is an IP address.The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-route-2" }'
options := &vpcv1.UpdateVPCRouteOptions{} options.SetVPCID(vpcID) options.SetID(routeID) options.SetName(name) route, response, err := vpcService.UpdateVPCRoute(options)
UpdateVpcRouteOptions updateVpcRouteOptions = new UpdateVpcRouteOptions.Builder() .vpcId(vpcId) .id(id) .name(name) .build(); Response<Route> response = service.updateVpcRoute(updateVpcRouteOptions).execute(); Route route = response.getResult();
const params = { vpcId, id, name: 'my-vpc-route', }; const response = await vpcService.updateVpcRoute(params);
response = service.update_vpc_route( vpc_id, id, name='my-vpc-route', )
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
creator
Status Code
The route was updated successfully.
An invalid route patch was provided.
A route with the specified identifier could not be found.
The route cannot be updated while it is being deleted.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route-updated", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
List all routing tables for a VPC
This request lists all routing tables for a VPC. Each subnet in a VPC is associated with a routing table, which controls delivery of packets sent on that subnet according to the action of the most specific matching route in the table. If multiple equally-specific routes exist, traffic will be distributed across them. If no routes match, delivery will be controlled by the system's built-in routes.
GET /vpcs/{vpc_id}/routing_tables
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to routing tables with an
is_default
property matching the specified value.
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListVPCRoutingTablesOptions(vpcID) routingTableCollection, response, err := vpcService.ListVPCRoutingTables(options)
ListVpcRoutingTablesOptions listVpcRoutingTablesOptions = new ListVpcRoutingTablesOptions.Builder() .vpcId(vpcId) .build(); Response<RoutingTableCollection> response = service.listVpcRoutingTables(listVpcRoutingTablesOptions).execute(); RoutingTableCollection routingTableCollection = response.getResult();
const response = await vpcService.listVpcRoutingTables({vpcId});
routing_table_collection = vpc_service.list_vpc_routing_tables( vpc_id=vpcId).get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of routing tables
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The routing tables were retrieved successfully.
The specified VPC could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables?limit=50" }, "limit": 50, "routing_tables": [ { "accept_routes_from": [ { "resource_type": "vpn_gateway" }, { "resource_type": "vpn_server" } ], "advertise_routes_to": [ "direct_link", "transit_gateway" ], "created_at": "2019-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "is_default": true, "lifecycle_state": "stable", "name": "minty-electric-energy-modeling", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/ae54c371-56be-4306-91bd-bb64df239d69", "id": "ae54c371-56be-4306-91bd-bb64df239d69", "name": "my-route-1" } ], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" }, { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet-2", "resource_type": "subnet" } ] }, { "accept_routes_from": [], "advertise_routes_to": [ "direct_link" ], "created_at": "2019-01-03T17:36:24Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "id": "eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "is_default": false, "lifecycle_state": "stable", "name": "my-routing-table-2", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [], "subnets": [] } ], "total_count": 2 }
Create a routing table for a VPC
This request creates a routing table from a routing table prototype object. The prototype object is structured in the same way as a retrieved routing table, and contains the information necessary to create the new routing table.
POST /vpcs/{vpc_id}/routing_tables
Request
Path Parameters
The VPC identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The routing table prototype object
The filters specifying the resources that may create routes in this routing table.
Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.Allowable values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
[]
The name for this routing table. The name must not be used by another routing table in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-routing-table-1
If set to
true
, this routing table will be used to route traffic that originates from Direct Link to this VPC. The VPC must not already have a routing table with this property set totrue
.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.If Classic Access is enabled for this VPC, and this property is set to
true
, its incoming traffic will also be routed according to this routing table.Default:
false
If set to
true
, this routing table will be used to route traffic that originates from the internet. For this to succeed, the VPC must not already have a routing table with this property set totrue
.Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Default:
false
If set to
true
, this routing table will be used to route traffic that originates from Transit Gateway to this VPC. The VPC must not already have a routing table with this property set totrue
.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Default:
false
If set to
true
, this routing table will be used to route traffic that originates from subnets in other zones in this VPC. The VPC must not already have a routing table with this property set totrue
.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Default:
false
The prototype objects for routes to create for this routing table. If unspecified, the routing table will be created with no routes.
curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-routing-table" }'
routeName := "my-route" action := "delegate" routePrototypeModel := &vpcv1.RoutePrototype{ Action: &action, NextHop: &vpcv1.RouteNextHopPrototypeRouteNextHopIP{ Address: addressPrefix, }, Name: &routeName, Destination: &destination, Zone: &vpcv1.ZoneIdentityByName{ Name: &zoneName, }, } name := "my-routing-table" options := &vpcv1.CreateVPCRoutingTableOptions{ VPCID: &vpcID, Name: &name, Routes: []vpcv1.RoutePrototype{*routePrototypeModel}, } routingTable, response, err := vpcService.CreateVPCRoutingTable(options)
RouteNextHopPrototypeRouteNextHopIP routeNextHopPrototypeModel = new RouteNextHopPrototypeRouteNextHopIP.Builder() .address("192.168.3.4") .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); RoutePrototype routePrototypeModel = new RoutePrototype.Builder() .action("delegate") .nextHop(routeNextHopPrototypeModel) .name("my-route") .destination("192.168.3.0/24") .zone(zoneIdentityModel) .build(); CreateVpcRoutingTableOptions createVpcRoutingTableOptions = new CreateVpcRoutingTableOptions.Builder() .vpcId(vpcId) .name("my-routing-table") .routes(new java.util.ArrayList<RoutePrototype>(java.util.Arrays.asList(routePrototypeModel))) .build(); Response<RoutingTable> response = service.createVpcRoutingTable(createVpcRoutingTableOptions).execute();
const routeNextHopPrototypeModel = { address: '192.168.3.4', }; const zoneIdentityModel = { name: zoneName, }; const routePrototypeModel = { action: 'delegate', next_hop: routeNextHopPrototypeModel, name: 'my-route', destination: '192.168.3.0/24', zone: zoneIdentityModel, }; const params = { vpcId, name: 'my-routing-table', routes: [routePrototypeModel], }; const response = await vpcService.createVpcRoutingTable(params);
route_next_hop_prototype_model = {'address': '192.168.3.4'} zone_identity_model = { 'name': zoneName } route_prototype_model = { 'action': 'delegate', 'next_hop': route_next_hop_prototype_model, 'name': 'my-route', 'destination': '192.168.3.0/24', 'zone': zone_identity_model } create_vpc_routing_table_response = vpc_service.create_vpc_routing_table( vpc_id, name='my-routing-table', routes=[route_prototype_model]) routing_table = create_vpc_routing_table_response.get_result()
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for this routing table.
The subnets to which this routing table is attached
Status Code
The routing table was created successfully.
An invalid routing table prototype object was provided.
The specified VPC could not be found.
{ "accept_routes_from": [], "advertise_routes_to": [ "direct_link", "transit_gateway" ], "created_at": "2019-01-03T17:36:24Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "id": "eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "is_default": false, "lifecycle_state": "stable", "name": "my-routing-table", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" } ] }
Delete a VPC routing table
This request deletes a routing table. A routing table cannot be deleted if it is associated with any subnets in the VPC. Additionally, a VPC's default routing table cannot be deleted. This operation cannot be reversed.
DELETE /vpcs/{vpc_id}/routing_tables/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPC identifier
The routing table identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$vpc_routing_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteVPCRoutingTableOptions( vpcID, routingTableID, ) response, err := vpcService.DeleteVPCRoutingTable(options)
DeleteVpcRoutingTableOptions deleteVpcRoutingTableOptions = new DeleteVpcRoutingTableOptions.Builder() .vpcId(vpcId) .id(routingTableId) .build(); Response<Void> response = service.deleteVpcRoutingTable(deleteVpcRoutingTableOptions).execute();
const response = await vpcService.deleteVpcRoutingTable({vpcId, id});
delete_vpc_routing_table_route_response = vpc_service.delete_vpc_routing_table_route( vpc_id, routing_table_id, id)
Response
Status Code
The routing table was deleted successfully.
The routing table is not allowed to be deleted.
A routing table with the specified identifier could not be found.
The routing table is in use and cannot be deleted.
The provided
If-Match
value does not match the current ETag value of the routing table
No Sample Response
Retrieve a VPC routing table
This request retrieves a single routing table specified by the identifier in the URL.
GET /vpcs/{vpc_id}/routing_tables/{id}
Request
Path Parameters
The VPC identifier
The routing table identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$vpc_routing_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVPCRoutingTableOptions{ VPCID: &vpcID, ID: &routingTableID, } routingTable, response, err := vpcService.GetVPCRoutingTable(options)
GetVpcRoutingTableOptions getVpcRoutingTableOptions = new GetVpcRoutingTableOptions.Builder() .vpcId(vpcId) .id(routingTableId) .build(); Response<RoutingTable> response = service.getVpcRoutingTable(getVpcRoutingTableOptions).execute();
const response = await vpcService.getVpcRoutingTable({vpcId, id});
get_vpc_routing_table_response = vpc_service.get_vpc_routing_table( vpc_id=vpcId, id=routingTableId)
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for this routing table.
The subnets to which this routing table is attached
Status Code
The routing table was retrieved successfully.
A routing table with the specified identifier could not be found.
{ "accept_routes_from": [], "advertise_routes_to": [], "created_at": "2019-01-03T17:36:24Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "id": "eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "is_default": false, "lifecycle_state": "stable", "name": "my-routing-table", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [], "subnets": [] }
Update a VPC routing table
This request updates a routing table with the information in a provided routing table patch. The patch object is structured in the same way as a retrieved table and contains only the information to be updated.
PATCH /vpcs/{vpc_id}/routing_tables/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPC identifier
The routing table identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The routing table patch
The filters specifying the resources that may create routes in this routing table (replacing any existing filters). All routes created by resources that match a given filter will be removed when an existing filter is removed. Therefore, if an empty array is specified, all filters will be removed, resulting in all routes not directly created by the user being removed.
Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to, replacing any existing sources to advertise to. Routes in the table with
advertise
enabled will be advertised to these sources.Allowable values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The name for this routing table. The name must not be used by another routing table in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-routing-table-2
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC. Updating to
true
selects this routing table, provided no other routing table in the VPC already has this property set totrue
, and no subnets are attached to this routing table. Updating tofalse
deselects this routing table, provideddirect_link
is absent fromadvertise_routes_to
.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet. Updating to
true
selects this routing table, provided no other routing table in the VPC already has this property set totrue
. Updating tofalse
deselects this routing table.Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from Transit Gateway to this VPC. Updating to
true
selects this routing table, provided no other routing table in the VPC already has this property set totrue
, and no subnets are attached to this routing table. Updating tofalse
deselects this routing table, providedtransit_gateway
is absent fromadvertise_routes_to
.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.If Classic Access is enabled for this VPC, and this property is set to
true
, its incoming traffic will also be routed according to this routing table.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC. Updating to
true
selects this routing table, provided no other routing table in the VPC already has this property set totrue
, and no subnets are attached to this routing table. Updating tofalse
deselects this routing table.Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$vpc_routing_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-routing-table-updated" }'
name := "my-routing-table" routingTablePatchModel := &vpcv1.RoutingTablePatch{ Name: &name, } routingTablePatchModelAsPatch, _ := routingTablePatchModel.AsPatch() options := &vpcv1.UpdateVPCRoutingTableOptions{ VPCID: &vpcID, ID: &routingTableID, RoutingTablePatch: routingTablePatchModelAsPatch, } routingTable, response, err := vpcService.UpdateVPCRoutingTable(options)
RoutingTablePatch routingTablePatchModel = new RoutingTablePatch.Builder() .name("my-routing-table") .build(); Map<String, Object> routingTablePatchModelAsPatch = routingTablePatchModel.asPatch(); UpdateVpcRoutingTableOptions updateVpcRoutingTableOptions = new UpdateVpcRoutingTableOptions.Builder() .vpcId(vpcId) .id(routingTableId) .routingTablePatch(routingTablePatchModelAsPatch) .build(); Response<RoutingTable> response = service.updateVpcRoutingTable(updateVpcRoutingTableOptions).execute();
const params = { vpcId, id, name: 'my-routing-table', }; const response = await vpcService.updateVpcRoutingTable(params);
routing_table_patch_model = { 'name': 'my-routing-table', } update_vpc_routing_table_response = vpc_service.update_vpc_routing_table( vpc_id, id, routing_table_patch=routing_table_patch_model) routing_table = update_vpc_routing_table_response.get_result()
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for this routing table.
The subnets to which this routing table is attached
Status Code
The routing table was updated successfully.
An invalid routing table patch was provided.
A routing table with the specified identifier could not be found.
The routing table cannot be updated while it is being deleted.
The provided
If-Match
value does not match the current ETag value of the routing table
{ "accept_routes_from": [], "advertise_routes_to": [ "transit_gateway" ], "created_at": "2019-01-03T17:36:24Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "id": "eee6e0f4-ff31-41b4-8584-3cdd50b8fffe", "is_default": false, "lifecycle_state": "stable", "name": "my-routing-table-updated", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [], "subnets": [] }
List all routes in a VPC routing table
This request lists all routes in a VPC routing table. If subnets are associated with this routing table, delivery of packets sent on a subnet is performed according to the action of the most specific matching route in the table (provided the subnet and route are in the same zone). If multiple equally-specific routes exist, the route with the highest priority will be used. If two matching routes have the same destination and priority, traffic will be distributed between them. If no routes match, delivery will be controlled by the system's built-in routes.
GET /vpcs/{vpc_id}/routing_tables/{routing_table_id}/routes
Request
Path Parameters
The VPC identifier
The routing table identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListVPCRoutingTableRoutesOptions( vpcID, routingTableID, ) routeCollection, response, err := vpcService.ListVPCRoutingTableRoutes(options)
ListVpcRoutingTableRoutesOptions listVpcRoutingTableRoutesOptions = new ListVpcRoutingTableRoutesOptions.Builder() .vpcId(vpcId) .routingTableId(routingTableId) .build(); Response<RouteCollection> response = service.listVpcRoutingTableRoutes(listVpcRoutingTableRoutesOptions).execute(); RouteCollection routeCollection = response.getResult();
const response = await vpcService.listVpcRoutingTableRoutes({ vpcId, routingTableId, });
list_vpc_routing_table_routes_response = vpc_service.list_vpc_routing_table_routes( vpc_id, routing_table_id) route_collection = list_vpc_routing_table_routes_response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/1a15dca5-7e33-45e1-b7c5-bc690e569531/routes?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of routes
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/1a15dca5-7e33-45e1-b7c5-bc690e569531/routes?start=a5e812a2-62c0-4555-86a5-907106760c56&limit=20
next
Status Code
The VPC routes were retrieved successfully.
The specified VPC routing table could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/ebdc5374-2050-4f9e-a357-27b5a1a664cf/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes?limit=50" }, "limit": 50, "routes": [ { "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }, { "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.0.2.5/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route-2", "next_hop": { "address": "192.0.2.6" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } } ], "total_count": 2 }
Create a route in a VPC routing table
This request creates a new VPC route from a VPC route prototype object. The prototype object is structured in the same way as a retrieved VPC route and contains the information necessary to create the route.
POST /vpcs/{vpc_id}/routing_tables/{routing_table_id}/routes
Request
Path Parameters
The VPC identifier
The routing table identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPC route prototype object
The destination CIDR of the route. The host identifier in the CIDR must be zero.
At most two routes per
zone
in a table can have the samedestination
andpriority
, and only if both routes have anaction
ofdeliver
and thenext_hop
is an IP address.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The zone to apply the route to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Allowable values: [
delegate
,delegate_vpc
,deliver
,drop
]Default:
deliver
Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.All routes in a routing table with the same
destination
andzone
must have the sameadvertise
value.Default:
false
The name for this route. The name must not be used by another route in the routing table. Names starting with
ibm-
are reserved for system-provided routes, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, it must be omitted or specified as0.0.0.0
.At most two routes per
zone
in a table can have the samedestination
andpriority
, and only when each route has anaction
ofdeliver
andnext_hop
is an IP address.next_hop
The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Default:
2
Example:
1
curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-route-1", "destination": "192.168.8.0/24", "next_hop": { "address": "10.0.1.2" }, "zone": { "name": "us-south-1" } }'
zoneIdentityModel := &vpcv1.ZoneIdentityByName{ Name: &zoneName, } options := vpcService.NewCreateVPCRoutingTableRouteOptions( vpcID, routingTableID, destination, zoneIdentityModel, ) route, response, err := vpcService.CreateVPCRoutingTableRoute(options)
ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateVpcRoutingTableRouteOptions createVpcRoutingTableRouteOptions = new CreateVpcRoutingTableRouteOptions.Builder() .vpcId(vpcId) .routingTableId(routingTableId) .destination("192.168.3.0/24") .zone(zoneIdentityModel) .build(); Response<Route> response = service.createVpcRoutingTableRoute(createVpcRoutingTableRouteOptions).execute(); Route route = response.getResult();
const routeNextHopPrototypeModel = { address: '192.168.3.4', }; const params = { vpcId, routingTableId, destination: '192.168.3.0/24', zone: { name: zoneName, }, action: 'delegate', nextHop: routeNextHopPrototypeModel, name: 'my-route', }; const response = await vpcService.createVpcRoutingTableRoute(params);
zone_identity_model = {'name': zoneName} route_next_hop_prototype_model = {'address': '192.168.3.4'} create_vpc_routing_table_route_response = vpc_service.create_vpc_routing_table_route( vpc_id, routing_table_id, destination='192.168.3.0/24', zone=zone_identity_model, action='delegate', next_hop=route_next_hop_prototype_model, name='my-route') route = create_vpc_routing_table_route_response.get_result()
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.
Status Code
The VPC route was created successfully.
An invalid VPC route prototype object was provided.
A VPC routing table with the specified identifier could not be found.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Delete a VPC routing table route
This request deletes a VPC route. This operation cannot be reversed. Only VPC routes with
an origin
of user
are allowed to be deleted.
DELETE /vpcs/{vpc_id}/routing_tables/{routing_table_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The routing table identifier
The VPC routing table route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteVPCRoutingTableRouteOptions{ VPCID: &vpcID, RoutingTableID: &routingTableID, ID: &routeID, } response, err := vpcService.DeleteVPCRoutingTableRoute(options)
DeleteVpcRoutingTableRouteOptions deleteVpcRoutingTableRouteOptions = new DeleteVpcRoutingTableRouteOptions.Builder() .vpcId(vpcId) .routingTableId(routingTableId) .id(routeId) .build(); Response<Void> response = service.deleteVpcRoutingTableRoute(deleteVpcRoutingTableRouteOptions).execute();
const response = await vpcService.deleteVpcRoutingTableRoute({ vpcId, routingTableId, id });
delete_vpc_routing_table_route_response = vpc_service.delete_vpc_routing_table_route( vpc_id, routing_table_id, id)
Retrieve a VPC routing table route
This request retrieves a single VPC route specified by the identifier in the URL path.
GET /vpcs/{vpc_id}/routing_tables/{routing_table_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The routing table identifier
The VPC routing table route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetVPCRoutingTableRouteOptions( vpcID, routingTableID, routeID, ) route, response, err := vpcService.GetVPCRoutingTableRoute(options)
GetVpcRoutingTableRouteOptions getVpcRoutingTableRouteOptions = new GetVpcRoutingTableRouteOptions.Builder() .vpcId(vpcId) .routingTableId(routingTableId) .id(routeId) .build(); Response<Route> response = service.getVpcRoutingTableRoute(getVpcRoutingTableRouteOptions).execute();
const response = await vpcService.getVpcRoutingTableRoute({ vpcId, routingTableId, id, });
get_vpc_routing_table_route_response = vpc_service.get_vpc_routing_table_route( vpc_id, routing_table_id, id)
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.
Status Code
The VPC route was retrieved successfully.
The specified VPC route could not be found.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Update a VPC routing table route
This request updates a VPC route with the information provided in a route patch object.
The patch object is structured in the same way as a retrieved VPC route and needs to
contain only the information to be updated. Only VPC routes with an origin
of user
are allowed to be updated.
PATCH /vpcs/{vpc_id}/routing_tables/{routing_table_id}/routes/{id}
Request
Path Parameters
The VPC identifier
The routing table identifier
The VPC routing table route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPC route patch.
Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.Since all routes in a routing table with the same
destination
andzone
must have the sameadvertise
value, this property can only be changed for routes with a uniquedestination
andzone
in the routing table. For more information, see Advertising routes.The name for this route. The name must not be used by another route in the routing table. Names starting with
ibm-
are reserved for system-provided routes, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-route-2
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, specify0.0.0.0
or remove it by specifyingnull
.At most two routes per
zone
in a table can have the samedestination
andpriority
, and only when each route has anaction
ofdeliver
andnext_hop
is an IP address.The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpc-route-updated" }'
name := "my-route" routePatchModel := &vpcv1.RoutePatch{ Name: &name, } routePatchModelAsPatch, _ := routePatchModel.AsPatch() options := &vpcv1.UpdateVPCRoutingTableRouteOptions{ VPCID: &vpcID, RoutingTableID: &routingTableID, ID: &routeID, RoutePatch: routePatchModelAsPatch, } route, response, err := vpcService.UpdateVPCRoutingTableRoute(options)
RoutePatch routePatchModel = new RoutePatch.Builder() .name("my-route") .build(); Map<String, Object> routePatchModelAsPatch = routePatchModel.asPatch(); UpdateVpcRoutingTableRouteOptions updateVpcRoutingTableRouteOptions = new UpdateVpcRoutingTableRouteOptions.Builder() .vpcId(vpcId) .routingTableId(routingTableId) .id(routeId) .routePatch(routePatchModelAsPatch) .build(); Response<Route> response = service.updateVpcRoutingTableRoute(updateVpcRoutingTableRouteOptions).execute();
const params = { vpcId, routingTableId, id, name: 'my-route', }; const response = await vpcService.updateVpcRoutingTableRoute(params);
route_patch_model = {'name': 'my-route'} update_vpc_routing_table_route_response = vpc_service.update_vpc_routing_table_route( vpc_id, routing_table_id, id, route_patch=route_patch_model)
Response
The action to perform with a packet matching the route:
delegate
: delegate to system-provided routesdelegate_vpc
: delegate to system-provided routes, ignoring Internet-bound routesdeliver
: deliver the packet to the specifiednext_hop
drop
: drop the packet
Possible values: [
delegate
,delegate_vpc
,deliver
,drop
]Indicates whether this route will be advertised to the ingress sources specified by the
advertise_routes_to
routing table property.The date and time that the route was created
The destination CIDR of the route
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The URL for this route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/8e454ead-0db7-48ac-9a8b-2698d8c470a7/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1a15dca5-7e33-45e1-b7c5-bc690e569531
The lifecycle state of the route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this route. The name is unique across all routes in the routing table.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-route-1
If
action
isdeliver
, the next hop that packets will be delivered to. For otheraction
values, itsaddress
will be0.0.0.0
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
next_hop
The origin of this route:
service
: route was directly created by a serviceuser
: route was directly created by a user
The enumerated values for this property may expand in the future.
Possible values: [
service
,user
]The priority of this route. Smaller values have higher priority.
If a routing table contains multiple routes with the same
zone
anddestination
, the route with the highest priority (smallest value) is selected. If two routes have the samedestination
andpriority
, traffic is distributed between them.Possible values: 0 ≤ value ≤ 4
Example:
1
The zone the route applies to.
If subnets are attached to the route's routing table, egress traffic from those subnets in this zone will be subject to this route. If this route's routing table has any of
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
orroute_vpc_zone_ingress
set totrue
, traffic from those ingress sources arriving in this zone will be subject to this route.Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, the resource that created the route. Routes with this property present cannot be directly deleted. All routes with an
origin
ofservice
will have this property set, and futureorigin
values may also have this property set.
Status Code
The VPC route was updated successfully.
An invalid VPC route patch was provided.
The VPC route is not allowed to be updated.
The specified VPC route could not be found.
The VPC route cannot be updated while it is being deleted.
{ "action": "deliver", "advertise": true, "created_at": "2019-08-19T04:42:42Z", "destination": "192.168.32.0/26", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_state": "stable", "name": "my-vpc-route-updated", "next_hop": { "address": "192.168.64.9" }, "origin": "user", "priority": 2, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
List all subnets
This request lists all subnets in the region. Subnets are contiguous ranges of IP addresses specified in CIDR block notation. Each subnet is within a particular zone and cannot span multiple zones or regions.
GET /subnets
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
Filters the collection to subnets with a
routing_table.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to subnets with a
routing_table.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table
curl -X GET "$vpc_api_endpoint/v1/subnets?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSubnetsOptions{} subnets, response, err := vpcService.ListSubnets(options)
ListSubnetsOptions listSubnetsOptions = new ListSubnetsOptions.Builder() .build(); Response<SubnetCollection> response = service.listSubnets(listSubnetsOptions).execute(); SubnetCollection subnetCollection = response.getResult();
const response = await vpcService.listSubnets();
response = service.list_subnets()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of subnets
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The subnets were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets?limit=50" }, "limit": 50, "subnets": [ { "available_ipv4_address_count": 251, "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "ip_version": "ipv4", "ipv4_cidr_block": "10.0.1.0/24", "name": "my-subnet-1", "network_acl": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "subnet", "routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "status": "pending", "total_ipv4_address_count": 256, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }, { "available_ipv4_address_count": 251, "created_at": "2019-01-29T10:53:46Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/10a4a88a-f20f-4d3e-9582-499ea21bbaf3", "id": "10a4a88a-f20f-4d3e-9582-499ea21bbaf3", "ip_version": "ipv4", "ipv4_cidr_block": "10.0.2.0/24", "name": "my-subnet-2", "network_acl": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "subnet", "routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "status": "pending", "total_ipv4_address_count": 256, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "total_count": 2 }
Create a subnet
This request creates a new subnet from a subnet prototype object. The prototype object is structured in the same way as a retrieved subnet, and contains the information necessary to create the new subnet. For this request to succeed, the prototype's CIDR block must not overlap with an existing subnet in the VPC.
POST /subnets
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The subnet prototype object
The VPC the subnet will reside in
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The IP version(s) to support for this subnet.
Allowable values: [
ipv4
]Default:
ipv4
Example:
ipv4
The name for this subnet. The name must not be used by another subnet in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-subnet
The network ACL to use for this subnet. If unspecified, the default network ACL for the VPC is used
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
network_acl
The public gateway to use for internet-bound traffic for this subnet. If unspecified, the subnet will not be attached to a public gateway.
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
public_gateway
The resource group to use. If unspecified, the account's default resource group will be used.
The routing table to use for this subnet. If unspecified, the default routing table for the VPC is used. The routing table properties
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
, androute_vpc_zone_ingress
must befalse
.The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
routing_table
The total number of IPv4 addresses required. Must be a power of 2. The VPC must have a default address prefix in the specified zone, and that prefix must have a free CIDR range with at least this number of addresses.
Possible values: 8 ≤ value ≤ 8388608
Example:
256
The zone this subnet will reside in
One of
curl -X POST "$vpc_api_endpoint/v1/subnets?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-subnet-1", "ipv4_cidr_block": "10.0.1.0/24", "ip_version": "ipv4", "zone": { "name": "us-south-1" }, "vpc": { "id": "a0819609-0997-4f92-9409-86c95ddf59d3" } }'
options := &vpcv1.CreateSubnetOptions{} options.SetSubnetPrototype(&vpcv1.SubnetPrototype{ Ipv4CidrBlock: &cidrBlock, Name: &name, Vpc: &vpcv1.VPCIdentity{ ID: &vpcID, }, Zone: &vpcv1.ZoneIdentity{ Name: &zone, }, }) subnet, response, err := vpcService.CreateSubnet(options)
VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); SubnetPrototypeSubnetByTotalCount subnetPrototypeModel = new SubnetPrototypeSubnetByTotalCount.Builder() .vpc(vpcIdentityModel) .name("my-subnet") .totalIpv4AddressCount(Long.valueOf("256")) .zone(zoneIdentityModel) .build(); CreateSubnetOptions createSubnetOptions = new CreateSubnetOptions.Builder() .subnetPrototype(subnetPrototypeModel) .build(); Response<Subnet> response = service.createSubnet(createSubnetOptions).execute(); Subnet subnet = response.getResult();
const vpcIdentityModel = { id: vpcID, }; const zoneIdentityModel = { name: zoneName, }; const subnetPrototypeModel = { name: 'my-subnet', ip_version: 'ipv4', vpc: vpcIdentityModel, ipv4_cidr_block: '10.235.0.0/24', zone: zoneIdentityModel, }; const params = { subnetPrototype: subnetPrototypeModel, }; const response = await vpcService.createSubnet(params);
network_acl_identity_model = {} network_acl_identity_model['id'] = network_acl_id public_gateway_identity_model = {} public_gateway_identity_model['id'] = public_gateway_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id vpc_identity_model = {} vpc_identity_model['id'] = vpc_id zone_identity_model = {} zone_identity_model['name'] = zoneName subnet_prototype_model = {} subnet_prototype_model['ip_version'] = 'both' subnet_prototype_model['name'] = 'my-subnet' subnet_prototype_model['network_acl'] = network_acl_identity_model subnet_prototype_model['public_gateway'] = public_gateway_identity_model subnet_prototype_model['resource_group'] = resource_group_identity_model subnet_prototype_model['vpc'] = vpc_identity_model subnet_prototype_model['total_ipv4_address_count'] = 256 subnet_prototype_model['ipv4_cidr_block'] = '10.245.0.0/24' subnet_prototype_model['zone'] = zone_identity_model subnet_prototype = subnet_prototype_model response = service.create_subnet(subnet_prototype)
Response
The number of IPv4 addresses in this subnet that are not in-use, and have not been reserved by the user or the provider.
Example:
15
The date and time that the subnet was created
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The IP version(s) supported by this subnet
Possible values: [
ipv4
]Example:
ipv4
The IPv4 range of the subnet, expressed in CIDR format
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
10.0.0.0/24
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The network ACL for this subnet
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
network_acl
The resource group for this subnet
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The routing table for this subnet
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
routing_table
The status of the subnet
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The total number of IPv4 addresses in this subnet.
Note: This is calculated as 2(32 - prefix length). For example, the prefix length
/24
gives:
2(32 - 24) = 28 = 256 addresses.Example:
256
The VPC this subnet resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this subnet resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The public gateway to use for internet-bound traffic for this subnet.
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
public_gateway
Status Code
The subnet was created successfully.
An invalid subnet prototype object was provided.
The subnet prototype object conflicts with another subnet in the VPC, or specifies a CIDR block outside of the VPC's address prefixes.
{ "available_ipv4_address_count": 251, "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "ip_version": "ipv4", "ipv4_cidr_block": "10.0.1.0/24", "name": "my-subnet-1", "network_acl": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "subnet", "routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "status": "pending", "total_ipv4_address_count": 256, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a subnet
This request deletes a subnet. This operation cannot be reversed. For this request to
succeed, the subnet must not be referenced by any bare metal server network interfaces,
instance network interfaces, virtual network interfaces, VPN gateways, or
load balancers. A delete operation automatically detaches the subnet from any network
ACLs, public gateways, or endpoint gateways. All flow log collectors with auto_delete
set to true
targeting the subnet or any resource in the subnet are automatically
deleted.
DELETE /subnets/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.subnet.subnet.detach
Generated for each resource that was attached to this subnet:
- a flow log collector
- a public gateway
- a network ACL
- a routing table
is.public-gateway.public-gateway.detach
Generated when the subnet has
public_gateway
set.is.network-acl.network-acl.detach
is.vpc.routing-table.detach
is.flow-log-collector.flow-log-collector.delete
Generated when a flow log collector that had
auto_delete
set totrue
was attached to the subnet.is.flow-log-collector.flow-log-collector.detach
Generated when a flow log collector was attached to the subnet
is.subnet.subnet.delete
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/subnets/$subnet_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSubnetOptions{} options.SetID(id) response, err := vpcService.DeleteSubnet(options)
DeleteSubnetOptions deleteSubnetOptions = new DeleteSubnetOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteSubnet(deleteSubnetOptions).execute();
const response = await vpcService.deleteSubnet({ id });
response = service.delete_subnet(id)
Retrieve a subnet
This request retrieves a single subnet specified by the identifier in the URL.
GET /subnets/{id}
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSubnetOptions{} options.SetID(subnetId) subnet, response, err := vpcService.GetSubnet(options)
GetSubnetOptions getSubnetOptions = new GetSubnetOptions.Builder() .id(id) .build(); Response<Subnet> response = service.getSubnet(getSubnetOptions).execute(); Subnet subnet = response.getResult();
const response = await vpcService.getSubnet({ id });
response = service.get_subnet(id)
Response
The number of IPv4 addresses in this subnet that are not in-use, and have not been reserved by the user or the provider.
Example:
15
The date and time that the subnet was created
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The IP version(s) supported by this subnet
Possible values: [
ipv4
]Example:
ipv4
The IPv4 range of the subnet, expressed in CIDR format
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
10.0.0.0/24
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The network ACL for this subnet
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
network_acl
The resource group for this subnet
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The routing table for this subnet
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
routing_table
The status of the subnet
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The total number of IPv4 addresses in this subnet.
Note: This is calculated as 2(32 - prefix length). For example, the prefix length
/24
gives:
2(32 - 24) = 28 = 256 addresses.Example:
256
The VPC this subnet resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this subnet resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The public gateway to use for internet-bound traffic for this subnet.
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
public_gateway
Status Code
The subnet was retrieved successfully.
A subnet with the specified identifier could not be found.
{ "available_ipv4_address_count": 251, "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4", "id": "1dfeccef-3ad6-4760-8653-a202bc795db4", "ip_version": "ipv4", "ipv4_cidr_block": "10.0.1.0/24", "name": "my-subnet-1", "network_acl": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "subnet", "routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "status": "pending", "total_ipv4_address_count": 256, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a subnet
This request updates a subnet with the information in a provided subnet patch. The subnet patch object is structured in the same way as a retrieved subnet and contains only the information to be updated.
PATCH /subnets/{id}
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The subnet patch
The name for this subnet. The name must not be used by another subnet in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-subnet
The network ACL to use for this subnet.
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
network_acl
The public gateway to use for internet-bound traffic for this subnet.
The routing table to use for this subnet. The routing table properties
route_direct_link_ingress
,route_internet_ingress
,route_transit_gateway_ingress
, androute_vpc_zone_ingress
must befalse
.The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
routing_table
curl -X PATCH "$vpc_api_endpoint/v1/subnets/$subnet_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-subnet-1-updated" }'
options := &vpcv1.UpdateSubnetOptions{} options.SetID(id) options.SetName(name) subnet, response, err := vpcService.UpdateSubnet(options)
UpdateSubnetOptions updateSubnetOptions = new UpdateSubnetOptions.Builder() .id(id) .name(name) .build(); Response<Subnet> response = service.updateSubnet(updateSubnetOptions).execute(); Subnet subnet = response.getResult();
const response = await vpcService.updateSubnet({ id, name: 'my-subnet' });
network_acl_identity_model = {} network_acl_identity_model['id'] = network_acl_id public_gateway_identity_model = {} public_gateway_identity_model['id'] = public_gateway_id name = 'my-subnet' network_acl = network_acl_identity_model public_gateway = public_gateway_identity_model response = service.update_subnet( id, name=name, network_acl=network_acl, public_gateway=public_gateway, )
Response
The number of IPv4 addresses in this subnet that are not in-use, and have not been reserved by the user or the provider.
Example:
15
The date and time that the subnet was created
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The IP version(s) supported by this subnet
Possible values: [
ipv4
]Example:
ipv4
The IPv4 range of the subnet, expressed in CIDR format
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
10.0.0.0/24
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The network ACL for this subnet
Examples:ViewThe CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
network_acl
The resource group for this subnet
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The routing table for this subnet
Examples:ViewThe URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
routing_table
The status of the subnet
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The total number of IPv4 addresses in this subnet.
Note: This is calculated as 2(32 - prefix length). For example, the prefix length
/24
gives:
2(32 - 24) = 28 = 256 addresses.Example:
256
The VPC this subnet resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this subnet resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The public gateway to use for internet-bound traffic for this subnet.
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
public_gateway
Status Code
The subnet was updated successfully.
An invalid subnet patch was provided.
A subnet with the specified identifier could not be found.
{ "available_ipv4_address_count": 251, "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4", "id": "1dfeccef-3ad6-4760-8653-a202bc795db4", "ip_version": "ipv4", "ipv4_cidr_block": "10.0.1.0/24", "name": "my-subnet-1-updated", "network_acl": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "subnet", "routing_table": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "name": "my-routing-table", "resource_type": "routing_table" }, "status": "pending", "total_ipv4_address_count": 256, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Retrieve a subnet's attached network ACL
This request retrieves the network ACL attached to the subnet specified by the identifier in the URL.
GET /subnets/{id}/network_acl
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id/network_acl?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSubnetNetworkACLOptions{} options.SetID(subnetId) acls, response, err := vpcService.GetSubnetNetworkAcl(options)
GetSubnetNetworkAclOptions getSubnetNetworkAclOptions = new GetSubnetNetworkAclOptions.Builder() .id(id) .build(); Response<NetworkACL> response = service.getSubnetNetworkAcl(getSubnetNetworkAclOptions).execute(); NetworkACL networkAcl = response.getResult();
const response = await vpcService.getSubnetNetworkAcl({ id });
response = service.get_subnet_network_acl(id)
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
The resource group for this network ACL
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for this network ACL. If no rules exist, all traffic will be denied.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The attached network ACL was retrieved successfully.
The specified subnet could not be found.
{ "created_at": "2019-01-29T07:21:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/e9d38838-7531-4383-bd01-662e10527f29", "id": "e9d38838-7531-4383-bd01-662e10527f29", "name": "my-network-acl-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
Replace the network ACL for a subnet
This request replaces the existing network ACL for a subnet with the network ACL specified in the request body.
PUT /subnets/{id}/network_acl
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The network ACL identity
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/network_acl?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "id":"8ec3e730-f2b0-4855-a1a5-88be30024658" }'
options := &vpcv1.ReplaceSubnetNetworkACLOptions{} options.SetID(subnetId) options.SetNetworkACLIdentity(&vpcv1.NetworkACLIdentity{ID: &id}) acl, response, err := vpcService.ReplaceSubnetNetworkACL(options)
NetworkACLIdentityById networkAclIdentityModel = new NetworkACLIdentityById.Builder() .id(networkAclId) .build(); ReplaceSubnetNetworkAclOptions replaceSubnetNetworkAclOptions = new ReplaceSubnetNetworkAclOptions.Builder() .id(id) .networkAclIdentity(networkAclIdentityModel) .build(); Response<NetworkACL> response = service.replaceSubnetNetworkAcl(replaceSubnetNetworkAclOptions).execute(); NetworkACL networkAcl = response.getResult();
const params = { id, networkAclIdentity: { id: aclID, }, }; const response = await vpcService.replaceSubnetNetworkAcl(params);
network_acl_identity_model = {} network_acl_identity_model['id'] = network_acl_id network_acl_identity = network_acl_identity_model response = service.replace_subnet_network_acl( id, network_acl_identity)
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
The resource group for this network ACL
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for this network ACL. If no rules exist, all traffic will be denied.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The network ACL was attached successfully.
An invalid request body was provided.
A subnet with the specified identifier could not be found.
{ "created_at": "2019-01-29T07:21:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/8ec3e730-f2b0-4855-a1a5-88be30024658", "id": "8ec3e730-f2b0-4855-a1a5-88be30024658", "name": "my-network-acl-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/8ec3e730-f2b0-4855-a1a5-88be30024658/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/8ec3e730-f2b0-4855-a1a5-88be30024658/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
Detach a public gateway from a subnet
This request detaches the public gateway from the subnet specified by the subnet identifier in the URL.
DELETE /subnets/{id}/public_gateway
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/subnets/$subnet_id/public_gateway?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" \
options := &vpcv1.UnsetSubnetPublicGatewayOptions{} options.SetID(id) response, err := vpcService.UnsetSubnetPublicGateway(options)
UnsetSubnetPublicGatewayOptions unsetSubnetPublicGatewayOptions = new UnsetSubnetPublicGatewayOptions.Builder() .id(id) .build(); Response<Void> response = service.unsetSubnetPublicGateway(unsetSubnetPublicGatewayOptions).execute();
const response = await vpcService.unsetSubnetPublicGateway({ id });
response = service.unset_subnet_public_gateway(id)
Retrieve a subnet's attached public gateway
This request retrieves the public gateway attached to the subnet specified by the identifier in the URL.
GET /subnets/{id}/public_gateway
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id/public_gateway?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSubnetPublicGatewayOptions{} options.SetID(subnetId) publicGateway, response, err := vpcService.GetSubnetPublicGateway(options)
GetSubnetPublicGatewayOptions getSubnetPublicGatewayOptions = new GetSubnetPublicGatewayOptions.Builder() .id(id) .build(); Response<PublicGateway> response = service.getSubnetPublicGateway(getSubnetPublicGatewayOptions).execute(); PublicGateway publicGateway = response.getResult();
const response = await vpcService.getSubnetPublicGateway({ id });
response = service.get_subnet_public_gateway(id)
Response
The date and time that the public gateway was created
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The floating IP bound to this public gateway.
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
floating_ip
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource group for this public gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this public gateway
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The VPC this public gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this public gateway resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The attached public gateway was retrieved successfully.
The specified subnet could not be found or has no public gateway.
{ "created_at": "2019-01-27T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/d4d3ef82-bebb-446e-bbe4-038bc82f6776", "id": "ba1b3bf9-27ab-498d-8aac-c30b09b5555b", "name": "my-public-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Attach a public gateway to a subnet
This request attaches the public gateway, specified in the request body, to the subnet specified by the subnet identifier in the URL. The public gateway must have the same VPC and zone as the subnet.
PUT /subnets/{id}/public_gateway
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.subnet.subnet.attach
is.subnet.subnet.detach
Generated for the replaced public gateway (if any)
is.public-gateway.public-gateway.detach
Generated for the replaced public gateway (if any)
is.public-gateway.public-gateway.attach
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The public gateway identity
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/public_gateway?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "id": "4fd00a61-fe63-4186-81c9-f7253b5c1cd7" }'
options := &vpcv1.SetSubnetPublicGatewayOptions{} options.SetID(subnetId) options.SetPublicGatewayIdentity(&vpcv1.PublicGatewayIdentity{ ID: &id, }) publicGateway, response, err := vpcService.SetSubnetPublicGateway(options)
PublicGatewayIdentityById publicGatewayIdentityModel = new PublicGatewayIdentityById.Builder() .id(publicGatewayId) .build(); SetSubnetPublicGatewayOptions setSubnetPublicGatewayOptions = new SetSubnetPublicGatewayOptions.Builder() .id(id) .publicGatewayIdentity(publicGatewayIdentityModel) .build(); Response<PublicGateway> response = service.setSubnetPublicGateway(setSubnetPublicGatewayOptions).execute(); PublicGateway publicGateway = response.getResult();
const params = { id, publicGatewayIdentity: { id: publicGatewayId, }, }; const response = await vpcService.setSubnetPublicGateway(params);
public_gateway_identity_model = {} public_gateway_identity_model['id'] = public_gateway_id public_gateway_identity = public_gateway_identity_model response = service.set_subnet_public_gateway( id, public_gateway_identity)
Response
The date and time that the public gateway was created
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The floating IP bound to this public gateway.
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
floating_ip
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource group for this public gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this public gateway
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The VPC this public gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this public gateway resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The public gateway was attached successfully.
An invalid request body was provided.
A subnet with the specified identifier could not be found.
{ "created_at": "2019-01-27T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/4fd00a61-fe63-4186-81c9-f7253b5c1cd7", "id": "4fd00a61-fe63-4186-81c9-f7253b5c1cd7", "name": "my-public-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Retrieve a subnet's attached routing table
This request retrieves the routing table attached to the subnet specified by the identifier in the URL.
GET /subnets/{id}/routing_table
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id/routing_table?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
routingTable, response, err := vpcService.GetSubnetRoutingTable( vpcService.NewGetSubnetRoutingTableOptions(subnetId))
GetSubnetRoutingTableOptions getSubnetRoutingTableOptions = new GetSubnetRoutingTableOptions.Builder() .id(subnetID) .build(); Response<RoutingTable> response = service.getSubnetRoutingTable(getSubnetRoutingTableOptions).execute(); RoutingTable routingTable = response.getResult();
const response = await vpcService.getSubnetRoutingTable({ id });
routing_table = vpc_service.get_subnet_routing_table( id=subnet_id).get_result()
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for this routing table.
The subnets to which this routing table is attached
Status Code
The attached routing table was retrieved successfully.
The specified subnet could not be found.
{ "accept_routes_from": [ { "resource_type": "vpn_gateway" }, { "resource_type": "vpn_server" } ], "advertise_routes_to": [ "direct_link", "transit_gateway" ], "created_at": "2019-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "is_default": false, "lifecycle_state": "stable", "name": "minty-electric-energy-modeling", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/ae54c371-56be-4306-91bd-bb64df239d69", "id": "ae54c371-56be-4306-91bd-bb64df239d69", "name": "my-route-1" } ], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" }, { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet-2", "resource_type": "subnet" } ] }
Replace the routing table for a subnet
This request replaces the existing routing table for a subnet with the routing table specified in the request body.
For this request to succeed, the routing table route_direct_link_ingress
,
route_internet_ingress
, route_transit_gateway_ingress
, and route_vpc_zone_ingress
properties must be false
.
PUT /subnets/{id}/routing_table
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The routing table identity
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/routing_table?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "id":"6885e83f-03b2-4603-8a86-db2a0f55c840" }'
routingTableIdentityModel := &vpcv1.RoutingTableIdentityByID{ ID: routingTableID, } replaceSubnetRoutingTableOptions := vpcService.NewReplaceSubnetRoutingTableOptions( subnetId, routingTableIdentityModel, ) routingTable, response, err := vpcService.ReplaceSubnetRoutingTable( replaceSubnetRoutingTableOptions )
RoutingTableIdentityById routingTableIdentityModel = new RoutingTableIdentityById.Builder() .id(routingTableId) .build(); ReplaceSubnetRoutingTableOptions replaceSubnetRoutingTableOptions = new ReplaceSubnetRoutingTableOptions.Builder() .id(subnetId) .routingTableIdentity(routingTableIdentityModel) .build(); Response<RoutingTable> response = service.replaceSubnetRoutingTable(replaceSubnetRoutingTableOptions).execute();
const routingTableIdentityModel = { id: routingTableId, }; const params = { id, routingTableIdentity: routingTableIdentityModel, }; const response = await vpcService.replaceSubnetRoutingTable(params);
routing_table_identity_model = { 'id': routing_table_id, } routing_table = vpc_service.replace_subnet_routing_table( id=subnet_id, routing_table_identity=routing_table_identity_model).get_result( )
Response
The filters specifying the resources that may create routes in this routing table.
At present, only the
resource_type
filter is permitted, and only the valuesvpn_gateway
andvpn_server
are supported, but filter support is expected to expand in the future.Possible values: contains only unique items
Examples:ViewThe ingress sources to advertise routes to. Routes in the table with
advertise
enabled will be advertised to these sources.The enumerated values for this property may expand in the future.
Possible values: [
direct_link
,transit_gateway
]Possible values: number of items ≥ 0, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Examples:ViewThe date and time that this routing table was created
The URL for this routing table
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b/routing_tables/r006-6885e83f-03b2-4603-8a86-db2a0f55c840
The unique identifier for this routing table
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-6885e83f-03b2-4603-8a86-db2a0f55c840
Indicates whether this is the default routing table for this VPC
The lifecycle state of the routing table
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this routing table. The name is unique across all routing tables for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-routing-table-1
The resource type
Possible values: [
routing_table
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether this routing table is used to route traffic that originates from Direct Link to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from the internet.
Incoming traffic will be routed according to the routing table with two exceptions:
- Traffic destined for IP addresses associated with public gateways will not be subject to routes in this routing table.
- Routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.
Indicates whether this routing table is used to route traffic that originates from from Transit Gateway to this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.Indicates whether this routing table is used to route traffic that originates from subnets in other zones in this VPC.
Incoming traffic will be routed according to the routing table with one exception: routes with an
action
ofdeliver
are treated asdrop
unless thenext_hop
is an IP address in a subnet in the route'szone
that is able to accept traffic. Therefore, if an incoming packet matches a route with anext_hop
of a VPN gateway connection, the packet will be dropped.The routes for this routing table.
The subnets to which this routing table is attached
Status Code
The routing table was attached successfully.
An invalid request body was provided.
A subnet with the specified identifier could not be found.
{ "accept_routes_from": [ { "resource_type": "vpn_gateway" }, { "resource_type": "vpn_server" } ], "advertise_routes_to": [ "direct_link", "transit_gateway" ], "created_at": "2019-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840", "id": "6885e83f-03b2-4603-8a86-db2a0f55c840", "is_default": false, "lifecycle_state": "stable", "name": "minty-electric-energy-modeling", "resource_type": "routing_table", "route_direct_link_ingress": false, "route_internet_ingress": false, "route_transit_gateway_ingress": false, "route_vpc_zone_ingress": false, "routes": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routing_tables/6885e83f-03b2-4603-8a86-db2a0f55c840/routes/ae54c371-56be-4306-91bd-bb64df239d69", "id": "ae54c371-56be-4306-91bd-bb64df239d69", "name": "my-route-1" } ], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" }, { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet-2", "resource_type": "subnet" } ] }
List all reserved IPs in a subnet
This request lists all reserved IPs in a subnet. A reserved IP resource will exist for every address in the subnet which is not available for use.
GET /subnets/{subnet_id}/reserved_ips
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
address
,created_at
,name
]Default:
address
Example:
name
Filters the collection to resources with a
target.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
target.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Filters the collection to resources with a
target.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-resource
Filters the collection to resources with a
target.resource_type
property matching the specified value.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListSubnetReservedIpsOptions(subnet_id) reservedIPs, response, err := vpcService.ListSubnetReservedIps(options)
ListSubnetReservedIpsOptions listSubnetReservedIpsOptions = new ListSubnetReservedIpsOptions.Builder() .subnetId(subnetId) .build(); Response<ReservedIPCollection> response = service.listSubnetReservedIps(listSubnetReservedIpsOptions).execute();
const response = await vpcService.listSubnetReservedIps();
response = _service.list_subnet_reserved_ips(subnet_id) reserved_ips = response.get_result()['reserved_ips']
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of reserved IPs in this subnet
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The reserved IPs were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips?limit=50" }, "limit": 50, "reserved_ips": [ { "address": "10.240.0.6", "auto_delete": false, "created_at": "2020-07-24T19:52:13Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip" }, { "address": "10.240.0.7", "auto_delete": false, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "lifecycle_state": "stable", "name": "my-reserved-ip-2", "owner": "user", "resource_type": "subnet_reserved_ip" } ], "total_count": 2 }
Reserve an IP in a subnet
This request reserves an IP address in a subnet. If the provided prototype object
includes an address
, the address must not already be reserved.
POST /subnets/{subnet_id}/reserved_ips
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.subnet.reserved-ip.create
is.subnet.subnet.update
is.endpoint-gateway.endpoint-gateway.attach
Generated when
target
specifies an endpoint gatewayis.subnet.reserved-ip.attach
Generated when
target
is specifiedis.virtual-network-interface.virtual-network-interface.attach
Generated when
target
specifies a virtual network interface
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The reserved IP prototype object
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound. Must befalse
if the reserved IP is unbound.Default:
false
The name for this reserved IP. The name must not be used by another reserved IP in the 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.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-reserved-ip
The target to bind this reserved IP to. The target must be in the same VPC.
The following targets are supported:
- An endpoint gateway not already bound to a reserved IP in the subnet's zone.
- A virtual network interface.
If unspecified, the reserved IP will be created unbound.
curl -X POST "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-reserved-ip" }'
options := vpcService.NewCreateSubnetReservedIPOptions(subnet_id) options.Name = &name reservedIP, response, err := vpcService.CreateSubnetReservedIP(options)
CreateSubnetReservedIpOptions createSubnetReservedIpOptions = new CreateSubnetReservedIpOptions.Builder() .subnetId(subnetId) .name("my-reserved-ip") .build(); Response<ReservedIP> response = service.createSubnetReservedIp(createSubnetReservedIpOptions).execute();
const response = await vpcService.createSubnetReservedIp({ subnetId, name: 'my-subnet-reserved-ip', });
response = service.create_subnet_reserved_ip(subnet_id)
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The reserved IP was created successfully.
An invalid reserved IP prototype object was provided.
The subnet has no available IP addresses, or the reserved IP prototype object specifies an address that is already in use, or specifies a target that is already bound to a reserved IP in the subnet's zone.
{ "address": "10.240.0.6", "auto_delete": false, "created_at": "2020-07-24T19:52:13Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip" }
Delete a reserved IP
This request releases a reserved IP. This operation cannot be reversed.
For this request to succeed, the reserved IP must not be required by another resource, such as a bare metal server network interface, instance network interface or virtual network interface for which it is the primary IP. A provider-owned reserved IP is not allowed to be deleted.
DELETE /subnets/{subnet_id}/reserved_ips/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.subnet.subnet.update
is.subnet.reserved-ip.delete
is.subnet.reserved-ip.detach
Generated when the reserved IP was attached
is.endpoint-gateway.endpoint-gateway.detach
Generated when
target
specified an endpoint gatewayis.virtual-network-interface.virtual-network-interface.detach
Generated when
target
specified a virtual network interface
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteSubnetReservedIPOptions(subnet_id, id) response, err := vpcService.DeleteSubnetReservedIP(options)
DeleteSubnetReservedIpOptions deleteSubnetReservedIpOptions = new DeleteSubnetReservedIpOptions.Builder() .subnetId(subnetId) .id(id) .build(); Response<Void> response = service.deleteSubnetReservedIp(deleteSubnetReservedIpOptions).execute();
const response = await vpcService.deleteSubnetReservedIp({ subnetId, id, });
response = service.delete_subnet_reserved_ip(subnet_id, reserved_ip_id)
Retrieve a reserved IP
This request retrieves a single reserved IP specified by the identifier in the URL.
GET /subnets/{subnet_id}/reserved_ips/{id}
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetSubnetReservedIPOptions(subnet_id, id) reservedIP, response, err := vpcService.GetSubnetReservedIP(options)
GetSubnetReservedIpOptions getSubnetReservedIpOptions = new GetSubnetReservedIpOptions.Builder() .subnetId(subnetId) .id(id) .build(); Response<ReservedIP> response = service.getSubnetReservedIp(getSubnetReservedIpOptions).execute(); ReservedIP reservedIp = response.getResult();
const response = await vpcService.getSubnetReservedIp({ subnetId, id, });
response = service.get_subnet_reserved_ip(subnet_id, reserved_ip_id) if response.status_code == 200: reserved_ip = response.get_result()
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The reserved IP was retrieved successfully.
The specified reserved IP could not be found.
{ "address": "10.240.0.6", "auto_delete": false, "created_at": "2020-07-24T19:52:13Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip" }
Update a reserved IP
This request updates a reserved IP with the information in a provided reserved IP patch. The reserved IP patch object is structured in the same way as a retrieved reserved IP and contains only the information to be updated.
A provider-owned reserved IP is not allowed to be updated.
PATCH /subnets/{subnet_id}/reserved_ips/{id}
Request
Path Parameters
The subnet identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The reserved IP patch
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound. Must befalse
if the reserved IP is unbound.The name for this reserved IP. The name must not be used by another reserved IP in the subnet. Names starting with
ibm-
are reserved for provider-owned resources, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-reserved-ip
curl -X PATCH "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-reserved-ip-updated" }'
options := vpcService.NewUpdateSubnetReservedIPOptions(subnet_id, id) options.Name = &name reservedIP, response, err = vpcService.UpdateSubnetReservedIP(options)
UpdateSubnetReservedIpOptions updateSubnetReservedIpOptions = new UpdateSubnetReservedIpOptions.Builder() .subnetId(subnetId) .id(id) .name(name) .build(); Response<ReservedIP> response = service.updateSubnetReservedIp(updateSubnetReservedIpOptions).execute();
const response = await vpcService.updateSubnetReservedIp({ subnetId, id, name: 'my-reserved-ip', });
new_name = 'my-reserved-ip-updated' response = service.update_subnet_reserved_ip( subnet_id, reserved_ip_id, name=new_name)
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The reserved IP was updated successfully.
An invalid reserved IP patch was provided.
The specified reserved IP is owned by the provider.
The specified reserved IP could not be found.
The specified reserved IP is unbound and would be automatically deleted.
{ "address": "10.240.0.6", "auto_delete": false, "created_at": "2020-07-24T19:52:13Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1-updated", "owner": "user", "resource_type": "subnet_reserved_ip" }
List all images
This request lists all images available in the region. An image provides source data for a volume. Images are either system-provided, or created from another source, such as importing from Cloud Object Storage.
GET /images
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to images with a
status
property matching one of the specified comma-separated values.Allowable values: [
available
,deleting
,deprecated
,failed
,obsolete
,pending
,unusable
]Possible values: number of items ≥ 1, contains only unique items
Filters the collection to images with a
visibility
property matching the specified value.Allowable values: [
private
,public
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Filters the collection to images with a
user_data_format
property matching one of the specified comma-separated values.Allowable values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: number of items ≥ 1, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/images?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListImagesOptions{} options.SetVisibility(visibility) images, response, err := vpcService.ListImages(options)
ListImagesOptions listImagesOptions = new ListImagesOptions.Builder() .build(); Response<ImageCollection> response = service.listImages(listImagesOptions).execute(); ImageCollection imageCollection = response.getResult();
const response = await vpcService.listImages();
response = service.list_images()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images?limit=20
first
Collection of images
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The images were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50" }, "images": [ { "catalog_offering": { "managed": false }, "created_at": "2019-03-15T21:31:37Z", "crn": "crn:[...]", "encryption": "none", "file": {}, "href": "https://us-south.iaas.cloud.ibm.com/v1/images/5ccbc579-dc22-0def-46a8-9c2e9b502d37", "id": "5ccbc579-dc22-0def-46a8-9c2e9b502d37", "minimum_provisioned_size": 100, "name": "windows-2016-amd64", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Windows Server 2016 Standard Edition (amd64)", "family": "Windows Server", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/windows-2016-amd64", "name": "windows-2016-amd64", "user_data_format": "cloud_init", "vendor": "Microsoft", "version": "2016 Standard Edition" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "available", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "public" }, { "catalog_offering": { "managed": false }, "created_at": "2018-10-04T04:04:25Z", "crn": "crn:[...]", "encryption": "none", "file": {}, "href": "https://us-south.iaas.cloud.ibm.com/v1/images/e15b69f1-c701-f621-e752-70eda3df5695", "id": "e15b69f1-c701-f621-e752-70eda3df5695", "minimum_provisioned_size": 100, "name": "debian-9-amd64", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64", "name": "debian-9-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "9.x Stretch/Stable - Minimal Install" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "available", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "public" }, { "catalog_offering": { "managed": false }, "created_at": "2018-12-12T18:22:51Z", "crn": "crn:[...]", "encryption": "none", "file": {}, "href": "https://eu-de.iaas.cloud.ibm.com/v1/images/7eb4e35b-4257-56f8-d7da-326d85452591", "id": "7eb4e35b-4257-56f8-d7da-326d85452591", "minimum_provisioned_size": 100, "name": "my-image", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Ubuntu Linux 16.04 LTS Xenial Xerus Minimal Install (amd64)", "family": "Ubuntu Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-04-amd64", "name": "ubuntu-16-04-amd64", "user_data_format": "cloud_init", "vendor": "Canonical", "version": "16.04 LTS Xenial Xerus Minimal Install" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "available", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "public" } ], "limit": 50, "total_count": 3 }
Create an image
This request creates a new image from an image prototype object. The prototype object is structured in the same way as a retrieved image, and contains the information necessary to create the new image. If an image is being imported, a URL to the image file on object storage must be specified. If an image is being created from an existing volume, that volume must be specified.
POST /images
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The image prototype object
The deprecation date and time to set for this image.
The date and time must not be in the past, and must be earlier than
obsolescence_at
(ifobsolescence_at
is set).If unspecified, no deprecation date and time will be set.
If the deprecation date and time is reached while the image has a status of
pending
, the image's status will transition todeprecated
upon its successful creation (orobsolete
if the obsolescence date and time was also reached).The name for this image. The name must not be used by another image in the region. Names starting with
ibm-
are reserved for system-provided images, and are not allowed. If unspecified, the name will be a hyphenated list of randomly-selected words.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-image
The obsolescence date and time to set for this image.
The date and time must not be in the past, and must be later than
deprecation_at
(ifdeprecation_at
is set).If unspecified, no obsolescence date and time will be set.
If the obsolescence date and time is reached while the image has a status of
pending
, the image's status will transition toobsolete
upon its successful creation.The resource group to use. If unspecified, the account's default resource group will be used.
The file from which to create the image
The Cloud Object Storage location of the image file.
The image file format is specified by the file's extension, which must be either
qcow2
orvhd
.Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^cos:\/\/([^\/?#]*)([^?#]*)$
Example:
cos://us-south/custom-image-vpc-bucket/customImage-0.vhd
file
The supported operating system included in this image.
A base64-encoded, encrypted representation of the key that was used to encrypt the data for this image.
That representation is created by wrapping the key's value with the
encryption_key
root key (which must also be specified), using either Key Protect or the Hyper Protect Crypto Services.If unspecified, the imported image is treated as unencrypted.
The root key that was used to wrap the data key (which is ultimately represented as
encrypted_data_key
). Additionally, the root key will be used to encrypt volumes created from this image (unless an alternateencryption_key
is specified at volume creation).If unspecified, the imported image is treated as unencrypted.
Examples:View
One of
curl -X POST "$vpc_api_endpoint/v1/images?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-image", "file": { "href": "cos://us-south/my-bucket/my-image.qcow2" }, "operating_system": { "name": "debian-9-amd64" } }'
options := &vpcv1.CreateImageOptions{} cosID := "cos://cos-location-of-image-file" options.SetImagePrototype(&vpcv1.ImagePrototype{ Name: &name, File: &vpcv1.ImageFilePrototype{ Href: &cosID, }, }) image, response, err := vpcService.CreateImage(options)
ImageFilePrototype imageFilePrototypeModel = new ImageFilePrototype.Builder() .href(cosBucket) .build(); OperatingSystemIdentityByName operatingSystemIdentityModel = new OperatingSystemIdentityByName.Builder() .name(osName) .build(); ImagePrototypeImageByFile imagePrototypeModel = new ImagePrototypeImageByFile.Builder() .name("my-image") .file(imageFilePrototypeModel) .operatingSystem(operatingSystemIdentityModel) .build(); CreateImageOptions createImageOptions = new CreateImageOptions.Builder() .imagePrototype(imagePrototypeModel) .build(); Response<Image> response = service.createImage(createImageOptions).execute(); Image image = response.getResult();
const imageFilePrototypeModel = { href: cosBucket, }; const operatingSystemIdentityModel = { name: 'debian-9-amd64', }; const imagePrototypeModel = { name: 'my-image', file: imageFilePrototypeModel, operating_system: operatingSystemIdentityModel, }; const params = { imagePrototype: imagePrototypeModel, }; const response = await vpcService.createImage(params);
image_file_prototype_model = {} image_file_prototype_model['href']= cos_location operating_system_identity_model = {} operating_system_identity_model['name'] = 'ubuntu-16-amd64' resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id image_prototype_model = {} image_prototype_model['name'] = 'my-image' image_prototype_model['resource_group'] = resource_group_identity_model image_prototype_model['file'] = image_file_prototype_model image_prototype_model[ 'operating_system'] = operating_system_identity_model image_prototype = image_prototype_model response = service.create_image(image_prototype)
Response
The date and time that the image was created
The CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The type of encryption used on the image
Possible values: [
none
,user_managed
]Example:
user_managed
Details for the stored image file
Checksums for this image file.
This property may be absent if the associated image has a
status
ofpending
orfailed
.The SHA256 fingerprint of the image file.
Example:
e992a84f113d3a35d2145ca3e7aca4fc95fe6daf470a08d8af3422ee59c92e15
checksums
The size of the stored image file rounded up to the next gigabyte.
This property may be absent if the associated image has a
status
ofpending
orfailed
.Possible values: value ≥ 1
file
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource group for this image
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image:
- available: image can be used (provisionable)
- deleting: image is being deleted, and can no longer be used to provision new resources
- deprecated: image is administratively slated to become
obsolete
- failed: image is corrupt or did not pass validation
- obsolete: image administratively set to not be used for new resources
- pending: image is being imported and is not yet
available
- unusable: image cannot be used (see
status_reasons[]
for possible remediation)
The enumerated values for this property may expand in the future.
Possible values: [
available
,deleting
,deprecated
,failed
,obsolete
,pending
,unusable
]Possible values: number of items ≥ 0
The user data format for this image:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
The value for this property is inherited from
operating_system.user_data_format
.Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The visibility of this image.
private
: Visible only to this accountpublic
: Visible to all accounts
Possible values: [
private
,public
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The deprecation date and time (UTC) for this image.
If absent, no deprecation date and time has been set.
The key that will be used to encrypt volumes created from this image (unless an alternate
encryption_key
is specified at volume creation).This property will be present for images with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The minimum size (in gigabytes) of a volume onto which this image may be provisioned.
This property may be absent if the image has a
status
ofpending
orfailed
.The obsolescence date and time (UTC) for this image.
If absent, no obsolescence date and time has been set.
The operating system included in this image
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The volume used to create this image (this may be deleted). If absent, this image was not created from a volume.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
Status Code
The image was created successfully
An invalid image prototype object was provided.
The image prototype object specified a volume or encryption key that cannot be used in its current state.
{ "catalog_offering": { "managed": false }, "created_at": "2019-06-26T00:05:13.873893Z", "crn": "crn:[...]", "encryption": "none", "file": {}, "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72251a2e-d6c5-42b4-97b0-b5f8e8d1f479", "id": "72251a2e-d6c5-42b4-97b0-b5f8e8d1f479", "name": "my-image", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64", "name": "debian-9-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "9.x Stretch/Stable - Minimal Install" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "pending", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "private" }
Delete an image
This request deletes an image. Any active image export jobs will be completed first. This operation cannot be reversed. A system-provided image is not allowed to be deleted. Additionally, an image cannot be deleted if it:
- has a
status
ofdeleting
- has a
status
ofpending
with astatus_reasons
code ofimage_request_in_progress
- has
catalog_offering.managed
set totrue
DELETE /images/{id}
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/images/$image_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteImageOptions{} options.SetID(id) response, err := vpcService.DeleteImage(options)
DeleteImageOptions deleteImageOptions = new DeleteImageOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteImage(deleteImageOptions).execute();
const response = await vpcService.deleteImage({ id });
response = service.delete_image(id)
Retrieve an image
This request retrieves a single image specified by the identifier in the URL.
GET /images/{id}
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/images/$image_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetImageOptions{} options.SetID(imageID) image, response, err := vpcService.GetImage(options)
GetImageOptions getImageOptions = new GetImageOptions.Builder() .id(id) .build(); Response<Image> response = service.getImage(getImageOptions).execute(); Image image = response.getResult();
const response = await vpcService.getImage({ id });
response = service.get_image(id)
Response
The date and time that the image was created
The CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The type of encryption used on the image
Possible values: [
none
,user_managed
]Example:
user_managed
Details for the stored image file
Checksums for this image file.
This property may be absent if the associated image has a
status
ofpending
orfailed
.The SHA256 fingerprint of the image file.
Example:
e992a84f113d3a35d2145ca3e7aca4fc95fe6daf470a08d8af3422ee59c92e15
checksums
The size of the stored image file rounded up to the next gigabyte.
This property may be absent if the associated image has a
status
ofpending
orfailed
.Possible values: value ≥ 1
file
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource group for this image
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image:
- available: image can be used (provisionable)
- deleting: image is being deleted, and can no longer be used to provision new resources
- deprecated: image is administratively slated to become
obsolete
- failed: image is corrupt or did not pass validation
- obsolete: image administratively set to not be used for new resources
- pending: image is being imported and is not yet
available
- unusable: image cannot be used (see
status_reasons[]
for possible remediation)
The enumerated values for this property may expand in the future.
Possible values: [
available
,deleting
,deprecated
,failed
,obsolete
,pending
,unusable
]Possible values: number of items ≥ 0
The user data format for this image:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
The value for this property is inherited from
operating_system.user_data_format
.Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The visibility of this image.
private
: Visible only to this accountpublic
: Visible to all accounts
Possible values: [
private
,public
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The deprecation date and time (UTC) for this image.
If absent, no deprecation date and time has been set.
The key that will be used to encrypt volumes created from this image (unless an alternate
encryption_key
is specified at volume creation).This property will be present for images with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The minimum size (in gigabytes) of a volume onto which this image may be provisioned.
This property may be absent if the image has a
status
ofpending
orfailed
.The obsolescence date and time (UTC) for this image.
If absent, no obsolescence date and time has been set.
The operating system included in this image
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The volume used to create this image (this may be deleted). If absent, this image was not created from a volume.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
Status Code
The image was retrieved successfully
An image with the specified identifier could not be found.
{ "catalog_offering": { "managed": false }, "created_at": "2019-06-26T00:05:13.873893Z", "crn": "crn:[...]", "encryption": "none", "file": { "size": 10 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72251a2e-d6c5-42b4-97b0-b5f8e8d1f479", "id": "72251a2e-d6c5-42b4-97b0-b5f8e8d1f479", "minimum_provisioned_size": 100, "name": "my-image", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64", "name": "debian-9-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "9.x Stretch/Stable - Minimal Install" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "available", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "private" }
Update an image
This request updates an image with the information in a provided image patch. The image
patch object is structured in the same way as a retrieved image and contains only the
information to be updated. A system-provided image is not allowed to be updated. An
image with a status
of deleting
cannot be updated.
PATCH /images/{id}
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The image patch
The deprecation date and time to set for this image.
This cannot be set if the image has a
status
offailed
ordeleting
, or ifcatalog_offering.managed
istrue
.The date and time must not be in the past, and must be earlier than
obsolescence_at
(ifobsolescence_at
is set). Additionally, if the image status is currentlydeprecated
, the value cannot be changed (but may be removed).Specify
null
to remove an existing deprecation date and time. If the image status is currentlydeprecated
, it will becomeavailable
.If the deprecation date and time is reached while the image has a status of
pending
, the image's status will transition todeprecated
upon its successful creation (orobsolete
if the obsolescence date and time was also reached).The name for this image. The name must not be used by another image in the region. Names starting with
ibm-
are reserved for system-provided images, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-image
The obsolescence date and time to set for this image.
This cannot be set if the image has a
status
offailed
ordeleting
, or ifcatalog_offering.managed
istrue
.The date and time must not be in the past, and must be later than
deprecation_at
(ifdeprecation_at
is set). Additionally, if the image status is currentlyobsolete
, the value cannot be changed (but may be removed).Specify
null
to remove an existing obsolescence date and time. If the image status is currentlyobsolete
, it will becomedeprecated
ifdeprecation_at
is in the past. Otherwise, it will becomeavailable
.If the obsolescence date and time is reached while the image has a status of
pending
, the image's status will transition toobsolete
upon its successful creation.
curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name" : "my-image-updated" }'
options := &vpcv1.UpdateImageOptions{} options.SetID(id) options.SetName(name) image, response, err := vpcService.UpdateImage(options)
UpdateImageOptions updateImageOptions = new UpdateImageOptions.Builder() .id(id) .name("my-image") .build(); Response<Image> response = service.updateImage(updateImageOptions).execute(); Image image = response.getResult();
const response = await vpcService.updateImage({ id, name: 'my-image', });
response = service.update_image( id, name='my-custom-image', )
Response
The date and time that the image was created
The CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The type of encryption used on the image
Possible values: [
none
,user_managed
]Example:
user_managed
Details for the stored image file
Checksums for this image file.
This property may be absent if the associated image has a
status
ofpending
orfailed
.The SHA256 fingerprint of the image file.
Example:
e992a84f113d3a35d2145ca3e7aca4fc95fe6daf470a08d8af3422ee59c92e15
checksums
The size of the stored image file rounded up to the next gigabyte.
This property may be absent if the associated image has a
status
ofpending
orfailed
.Possible values: value ≥ 1
file
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource group for this image
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image:
- available: image can be used (provisionable)
- deleting: image is being deleted, and can no longer be used to provision new resources
- deprecated: image is administratively slated to become
obsolete
- failed: image is corrupt or did not pass validation
- obsolete: image administratively set to not be used for new resources
- pending: image is being imported and is not yet
available
- unusable: image cannot be used (see
status_reasons[]
for possible remediation)
The enumerated values for this property may expand in the future.
Possible values: [
available
,deleting
,deprecated
,failed
,obsolete
,pending
,unusable
]Possible values: number of items ≥ 0
The user data format for this image:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
The value for this property is inherited from
operating_system.user_data_format
.Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The visibility of this image.
private
: Visible only to this accountpublic
: Visible to all accounts
Possible values: [
private
,public
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The deprecation date and time (UTC) for this image.
If absent, no deprecation date and time has been set.
The key that will be used to encrypt volumes created from this image (unless an alternate
encryption_key
is specified at volume creation).This property will be present for images with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The minimum size (in gigabytes) of a volume onto which this image may be provisioned.
This property may be absent if the image has a
status
ofpending
orfailed
.The obsolescence date and time (UTC) for this image.
If absent, no obsolescence date and time has been set.
The operating system included in this image
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The volume used to create this image (this may be deleted). If absent, this image was not created from a volume.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
Status Code
The image was updated successfully
An invalid image patch was provided.
The image is not allowed to be updated.
An image with the specified identifier could not be found.
The image cannot be updated in its current state.
{ "catalog_offering": { "managed": false }, "created_at": "2019-06-24T21:34:08.39622Z", "crn": "crn:[...]", "encryption": "none", "file": { "size": 10 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/images/f2ecdc05-452b-4b9a-ab18-7e129f730c15", "id": "f2ecdc05-452b-4b9a-ab18-7e129f730c15", "minimum_provisioned_size": 100, "name": "my-image-updated", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64", "name": "debian-9-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "9.x Stretch/Stable - Minimal Install" }, "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "image", "status": "available", "status_reasons": [], "user_data_format": "cloud_init", "visibility": "private" }
Deprecate an image
This request deprecates an image, resulting in its status
becoming deprecated
and
deprecation_at
being set to the current date and time.
The image must:
- have a
status
ofavailable
- have
catalog_offering.managed
set tofalse
- not have
deprecation_at
set
The image must not have deprecation_at
set, must have catalog_offering.managed
set to
false
, and must have a status
of available
.
A system-provided image is not allowed to be deprecated.
POST /images/{id}/deprecate
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/images/$image_id/deprecate?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deprecateImageOptions := vpcService.NewDeprecateImageOptions( imageID, ) response, err := vpcService.DeprecateImage(deprecateImageOptions)
DeprecateImageOptions deprecateImageOptions = new DeprecateImageOptions.Builder() .id(imageId) .build(); Response<Void> response = vpcService.deprecateImage(deprecateImageOptions).execute();
const params = { id: imageId, }; const response = await vpcService.deprecateImage(params);
response = vpc_service.deprecate_image( id=imageId, )
Obsolete an image
This request obsoletes an image, resulting in its status
becoming obsolete
and
obsolescence_at
being set to the current date and time.
The image must:
- have a
status
ofavailable
ordeprecated
- have
catalog_offering.managed
set tofalse
- not have
deprecation_at
set in the future - not have
obsolescence_at
set
A system-provided image is not allowed to be obsoleted.
POST /images/{id}/obsolete
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/images/$image_id/obsolete?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
obsoleteImageOptions := vpcService.NewObsoleteImageOptions( imageID, ) response, err := vpcService.ObsoleteImage(obsoleteImageOptions)
ObsoleteImageOptions obsoleteImageOptions = new ObsoleteImageOptions.Builder() .id(imageId) .build(); Response<Void> response = vpcService.obsoleteImage(obsoleteImageOptions).execute();
const params = { id: imageId, }; const response = await vpcService.obsoleteImage(params);
response = vpc_service.obsolete_image( id=imageId, )
List all image export jobs
This request lists all export jobs for an image. Each job tracks the exporting of the image to another location, such as a bucket within cloud object storage.
The jobs will be sorted by their created_at
property values, with newest jobs first.
Jobs with identical created_at
property values will in turn be sorted by ascending
name
property values.
GET /images/{image_id}/export_jobs
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
name
property matching the exact specified name.
curl -X GET "$vpc_api_endpoint/v1/images/$image_id/export_jobs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listImageExportJobsOptions := &vpcv1.ListImageExportJobsOptions{ ImageID: &imageID, } imageExportJobs, response, err := vpcService.ListImageExportJobs(listImageExportJobsOptions)
ListImageExportJobsOptions listImageExportJobsOptions = new ListImageExportJobsOptions.Builder() .imageId(imageId) .build(); Response<ImageExportJobUnpaginatedCollection> response = vpcService.listImageExportJobs(listImageExportJobsOptions).execute(); ImageExportJobUnpaginatedCollection imageExportJobUnpaginatedCollection = response.getResult();
const params = { imageId: imageId, }; const response = await vpcService.listImageExportJobs(params);
response = vpc_service.list_image_export_jobs( image_id=imageId ) image_export_job_unpaginated_collection = response.get_result()
Response
Collection of image export jobs
Status Code
The image export jobs were retrieved successfully.
{ "export_jobs": [ { "created_at": "2022-06-23T01:09:02.000Z", "format": "qcow2", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a", "id": "r134-095e9baf-01d4-4e29-986e-20d26606b82a", "name": "my-image-export", "resource_type": "image_export_job", "started_at": "2022-06-23T01:15:34.000Z", "status": "running", "status_reasons": [], "storage_bucket": { "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:bucket-27200-lwx4cfvcue", "name": "bucket-27200-lwx4cfvcue" }, "storage_href": "cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2", "storage_object": { "name": "my-image-export.qcow2" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs?limit=50" }, "limit": 50, "total_count": 1 }
Create an image export job
This request creates and queues a new export job for the image specified in the URL using
the image export job prototype object. The image must be owned by the account and be in
the available
, deprecated
, obsolete
, or unusable
state. The prototype object is
structured in the same way as a retrieved image export job, and contains the information
necessary to create and queue the new image export job.
POST /images/{image_id}/export_jobs
Request
Path Parameters
The image identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The image export job prototype object
The Cloud Object Storage bucket to export the image to. The bucket must exist and an IAM service authorization must grant
Image Service for VPC
ofVPC Infrastructure Services
writer access to the bucket.The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The format to use for the exported image. If the image is encrypted, only
qcow2
is supported.Allowable values: [
qcow2
,vhd
]Default:
qcow2
The name for this image export job. The name must not be used by another export job for the image. If unspecified, the name will be a hyphenated list of randomly-selected words prefixed with the first 16 characters of the parent image name.
The exported image object name in Cloud Object Storage (
storage_object.name
in the response) will be based on this name. The object name will be unique within the bucket.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image-export
curl -X POST "$vpc_api_endpoint/v1/images/$image_id/export_jobs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-image-export", "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" } }'
cloudObjectStorageBucketIdentityModel := &vpcv1.CloudObjectStorageBucketIdentityCloudObjectStorageBucketIdentityByName{ Name: &[]string{"bucket-27200-lwx4cfvcue"}[0], } createImageExportJobOptions := &vpcv1.CreateImageExportJobOptions{ ImageID: &imageID, StorageBucket: cloudObjectStorageBucketIdentityModel, Format: &[]string{"qcow2"}[0], Name: &[]string{"my-image-export-job"}[0], } imageExportJob, response, err := vpcService.CreateImageExportJob(createImageExportJobOptions)
CloudObjectStorageBucketIdentityCloudObjectStorageBucketIdentityByName cloudObjectStorageBucketIdentityModel = new CloudObjectStorageBucketIdentityCloudObjectStorageBucketIdentityByName.Builder() .name("my-cos-bucket") .build(); CreateImageExportJobOptions createImageExportJobOptions = new CreateImageExportJobOptions.Builder() .imageId(imageId) .storageBucket(cloudObjectStorageBucketIdentityModel) .build(); Response<ImageExportJob> response = vpcService.createImageExportJob(createImageExportJobOptions).execute(); ImageExportJob imageExportJob = response.getResult();
const cloudObjectStorageBucketIdentityModel = { name: 'bucket-27200-lwx4cfvcue', }; const params = { imageId: imageId, storageBucket: cloudObjectStorageBucketIdentityModel, format: 'qcow2', name: 'my-image-export-job' }; const response = await vpcService.createImageExportJob(params);
cloud_object_storage_bucket_identity_model = { 'name': 'bucket-27200-lwx4cfvcue', } image_export_job = vpc_service.create_image_export_job( image_id=imageId, name='my-image-export-job', storage_bucket=cloud_object_storage_bucket_identity_model ).get_result()
Response
The date and time that the image export job was created.
The format of the exported image.
Possible values: [
qcow2
,vhd
]The URL for this image export job
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a
The unique identifier for this image export job
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-095e9baf-01d4-4e29-986e-20d26606b82a
The name for this image export job. The name must not be used by another export job for the image. Changing the name will not affect the exported image name,
storage_object.name
, orstorage_href
values.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image-export
The type of resource referenced
Possible values: [
image_export_job
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image export job:
deleting
: Export job is being deletedfailed
: Export job could not be completed successfullyqueued
: Export job is queuedrunning
: Export job is in progresssucceeded
: Export job was completed successfully
The exported image object is automatically deleted for
failed
jobs.Possible values: [
deleting
,failed
,queued
,running
,succeeded
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The Cloud Object Storage bucket of the exported image object.
The CRN of this Cloud Object Storage bucket
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:my-bucket
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The Cloud Object Storage location of the exported image object. The object at this location will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^cos:\/\/([^\/?#]*)([^?#]*)$
Example:
cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2
The Cloud Object Storage object for the exported image. This object will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Example:
my-image-export.qcow2
The name of this Cloud Object Storage object. Names are unique within a Cloud Object Storage bucket.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[a-zA-Z0-9/!-_.*'\(\)]
Example:
my-object
storage_object
The date and time that the image export job was completed.
If absent, the export job has not yet completed.
A base64-encoded, encrypted representation of the key that was used to encrypt the data for the exported image. This key can be unwrapped with the image's
encryption_key
root key using either Key Protect or Hyper Protect Crypto Services.If absent, the export job is for an unencrypted image.
Possible values: length ≥ 4, Value must match regular expression
^(?:[A-Za-z0-9+\\\/]{4})*(?:[A-Za-z0-9+\\\/]{2}==|[A-Za-z0-9+\\\/]{3}=|[A-Za-z0-9+\\\/]{4})$
The date and time that the image export job started running.
If absent, the export job has not yet started.
Status Code
The image export job was created successfully.
An invalid image export job prototype object was provided.
The image is not allowed to be exported.
The specified image cannot be exported in its current state.
{ "created_at": "2022-06-23T01:09:02.000Z", "format": "qcow2", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a", "id": "r134-095e9baf-01d4-4e29-986e-20d26606b82a", "name": "my-image-export", "resource_type": "image_export_job", "status": "queued", "status_reasons": [], "storage_bucket": { "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:bucket-27200-lwx4cfvcue", "name": "bucket-27200-lwx4cfvcue" }, "storage_href": "cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2", "storage_object": { "name": "my-image-export.qcow2" } }
Delete an image export job
This request deletes an image export job. This operation cannot be reversed. If the job has not completed, the job will be canceled, and the incomplete exported image object deleted. If the job has completed, the exported image object will not be deleted.
DELETE /images/{image_id}/export_jobs/{id}
Request
Path Parameters
The image identifier
The image export job identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/images/$image_id/export_jobs/$image_export_job_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteImageExportJobOptions := &vpcv1.DeleteImageExportJobOptions{ ImageID: &imageID, ID: &imageExportJobID, } response, err := vpcService.DeleteImageExportJob(deleteImageExportJobOptions)
DeleteImageExportJobOptions deleteImageExportJobOptions = new DeleteImageExportJobOptions.Builder() .imageId(imageId) .id(imageExportJobId) .build(); Response<Void> response = vpcService.deleteImageExportJob(deleteImageExportJobOptions).execute();
const params = { imageId: imageId, id: imageExportJobId, }; const response = await vpcService.deleteImageExportJob(params);
response = vpc_service.delete_image_export_job( image_id=imageId, id=imageExportJobId )
Retrieve an image export job
This request retrieves a single image export job specified by the identifier in the URL.
GET /images/{image_id}/export_jobs/{id}
Request
Path Parameters
The image identifier
The image export job identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/images/$image_id/export_jobs/$image_export_job_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getImageExportJobOptions := &vpcv1.GetImageExportJobOptions{ ImageID: &imageID, ID: &imageExportJobID, } imageExportJob, response, err := vpcService.GetImageExportJob(getImageExportJobOptions)
GetImageExportJobOptions getImageExportJobOptions = new GetImageExportJobOptions.Builder() .imageId(imageId) .id(imageExportJobId) .build(); Response<ImageExportJob> response = vpcService.getImageExportJob(getImageExportJobOptions).execute(); ImageExportJob imageExportJob = response.getResult();
const params = { imageId: imageId, id: imageExportJobId, }; const response = await vpcService.getImageExportJob(params);
response = vpc_service.get_image_export_job( image_id=imageId, id=imageExportJobId ) image_export_job = response.get_result()
Response
The date and time that the image export job was created.
The format of the exported image.
Possible values: [
qcow2
,vhd
]The URL for this image export job
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a
The unique identifier for this image export job
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-095e9baf-01d4-4e29-986e-20d26606b82a
The name for this image export job. The name must not be used by another export job for the image. Changing the name will not affect the exported image name,
storage_object.name
, orstorage_href
values.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image-export
The type of resource referenced
Possible values: [
image_export_job
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image export job:
deleting
: Export job is being deletedfailed
: Export job could not be completed successfullyqueued
: Export job is queuedrunning
: Export job is in progresssucceeded
: Export job was completed successfully
The exported image object is automatically deleted for
failed
jobs.Possible values: [
deleting
,failed
,queued
,running
,succeeded
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The Cloud Object Storage bucket of the exported image object.
The CRN of this Cloud Object Storage bucket
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:my-bucket
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The Cloud Object Storage location of the exported image object. The object at this location will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^cos:\/\/([^\/?#]*)([^?#]*)$
Example:
cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2
The Cloud Object Storage object for the exported image. This object will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Example:
my-image-export.qcow2
The name of this Cloud Object Storage object. Names are unique within a Cloud Object Storage bucket.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[a-zA-Z0-9/!-_.*'\(\)]
Example:
my-object
storage_object
The date and time that the image export job was completed.
If absent, the export job has not yet completed.
A base64-encoded, encrypted representation of the key that was used to encrypt the data for the exported image. This key can be unwrapped with the image's
encryption_key
root key using either Key Protect or Hyper Protect Crypto Services.If absent, the export job is for an unencrypted image.
Possible values: length ≥ 4, Value must match regular expression
^(?:[A-Za-z0-9+\\\/]{4})*(?:[A-Za-z0-9+\\\/]{2}==|[A-Za-z0-9+\\\/]{3}=|[A-Za-z0-9+\\\/]{4})$
The date and time that the image export job started running.
If absent, the export job has not yet started.
Status Code
The image export job was retrieved successfully.
The specified image export job could not be found.
{ "created_at": "2022-06-23T01:09:02.000Z", "format": "qcow2", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a", "id": "r134-095e9baf-01d4-4e29-986e-20d26606b82a", "name": "my-image-export", "resource_type": "image_export_job", "started_at": "2022-06-23T01:15:34.000Z", "status": "running", "status_reasons": [], "storage_bucket": { "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:bucket-27200-lwx4cfvcue", "name": "bucket-27200-lwx4cfvcue" }, "storage_href": "cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2", "storage_object": { "name": "my-image-export.qcow2" } }
Update an image export job
This request updates an image export job with the information in a provided image export job patch. The image export job patch object is structured in the same way as a retrieved image export job and contains only the information to be updated.
PATCH /images/{image_id}/export_jobs/{id}
Request
Path Parameters
The image identifier
The image export job identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The image export job patch
The name for this image export job. The name must not be used by another export job for the image. Changing the name will not affect the exported image name,
storage_object.name
, orstorage_href
values.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image-export
curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id/export_jobs/$image_export_job_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-image-export-updated" }'
imageExportJobPatchModel := &vpcv1.ImageExportJobPatch{ Name: &[]string{"image-export-job-updated"}[0], } imageExportJobPatchModelAsPatch, _ := imageExportJobPatchModel.AsPatch() updateImageExportJobOptions := &vpcv1.UpdateImageExportJobOptions{ ImageID: &imageID, ID: &imageExportJobID, ImageExportJobPatch: imageExportJobPatchModelAsPatch, } imageExportJob, response, err := vpcService.UpdateImageExportJob(updateImageExportJobOptions)
ImageExportJobPatch imageExportJobPatchModel = new ImageExportJobPatch.Builder() .build(); Map<String, Object> imageExportJobPatchModelAsPatch = imageExportJobPatchModel.asPatch(); UpdateImageExportJobOptions updateImageExportJobOptions = new UpdateImageExportJobOptions.Builder() .imageId(imageId) .id(imageExportJobId) .imageExportJobPatch(imageExportJobPatchModelAsPatch) .build(); Response<ImageExportJob> response = vpcService.updateImageExportJob(updateImageExportJobOptions).execute(); ImageExportJob imageExportJob = response.getResult();
const params = { imageId: imageId, id: imageExportJobId, name: 'my-image-export-job-updated', }; const response = await vpcService.updateImageExportJob(params);
image_export_job_patch_model = { 'name' : 'my-image-export-job-updated' } response = vpc_service.update_image_export_job( image_id=imageId, id=imageExportJobId, image_export_job_patch=image_export_job_patch_model ) image_export_job = response.get_result()
Response
The date and time that the image export job was created.
The format of the exported image.
Possible values: [
qcow2
,vhd
]The URL for this image export job
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a
The unique identifier for this image export job
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-095e9baf-01d4-4e29-986e-20d26606b82a
The name for this image export job. The name must not be used by another export job for the image. Changing the name will not affect the exported image name,
storage_object.name
, orstorage_href
values.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image-export
The type of resource referenced
Possible values: [
image_export_job
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this image export job:
deleting
: Export job is being deletedfailed
: Export job could not be completed successfullyqueued
: Export job is queuedrunning
: Export job is in progresssucceeded
: Export job was completed successfully
The exported image object is automatically deleted for
failed
jobs.Possible values: [
deleting
,failed
,queued
,running
,succeeded
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The Cloud Object Storage bucket of the exported image object.
The CRN of this Cloud Object Storage bucket
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:my-bucket
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The Cloud Object Storage location of the exported image object. The object at this location will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^cos:\/\/([^\/?#]*)([^?#]*)$
Example:
cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2
The Cloud Object Storage object for the exported image. This object will not exist until the job completes successfully. The exported image object is not managed by the IBM VPC service, and may be removed or replaced with a different object by any user or service with IAM authorization to the storage bucket.
Example:
my-image-export.qcow2
The name of this Cloud Object Storage object. Names are unique within a Cloud Object Storage bucket.
Possible values: 1 ≤ length ≤ 1024, Value must match regular expression
^[a-zA-Z0-9/!-_.*'\(\)]
Example:
my-object
storage_object
The date and time that the image export job was completed.
If absent, the export job has not yet completed.
A base64-encoded, encrypted representation of the key that was used to encrypt the data for the exported image. This key can be unwrapped with the image's
encryption_key
root key using either Key Protect or Hyper Protect Crypto Services.If absent, the export job is for an unencrypted image.
Possible values: length ≥ 4, Value must match regular expression
^(?:[A-Za-z0-9+\\\/]{4})*(?:[A-Za-z0-9+\\\/]{2}==|[A-Za-z0-9+\\\/]{3}=|[A-Za-z0-9+\\\/]{4})$
The date and time that the image export job started running.
If absent, the export job has not yet started.
Status Code
The image export job was updated successfully.
An invalid image export job patch was provided.
An image export job with the specified identifier could not be found.
{ "created_at": "2022-06-23T01:09:02.000Z", "format": "qcow2", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8/export_jobs/r134-095e9baf-01d4-4e29-986e-20d26606b82a", "id": "r134-095e9baf-01d4-4e29-986e-20d26606b82a", "name": "my-image-export-updated", "resource_type": "image_export_job", "started_at": "2022-06-23T01:15:34.000Z", "status": "running", "status_reasons": [], "storage_bucket": { "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1a0ec336-f391-4091-a6fb-5e084a4c56f4:bucket:bucket-27200-lwx4cfvcue", "name": "bucket-27200-lwx4cfvcue" }, "storage_href": "cos://us-south/bucket-27200-lwx4cfvcue/my-image-export.qcow2", "storage_object": { "name": "my-image-export.qcow2" } }
List all operating systems
This request lists all operating systems in the region.
GET /operating_systems
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/operating_systems?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListOperatingSystemsOptions{} operatingSystems, response, err := vpcService.ListOperatingSystems(options)
ListOperatingSystemsOptions listOperatingSystemsOptions = new ListOperatingSystemsOptions.Builder() .build(); Response<OperatingSystemCollection> response = service.listOperatingSystems(listOperatingSystemsOptions).execute(); OperatingSystemCollection operatingSystemCollection = response.getResult();
const response = await vpcService.listOperatingSystems();
response = service.list_operating_systems()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of operating systems
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The operating systems were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems?limit=50" }, "limit": 50, "operating_systems": [ { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "CentOS 7.x - Minimal Install (amd64)", "family": "CentOS", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/centos-7-amd64", "name": "centos-7-amd64", "user_data_format": "cloud_init", "vendor": "CentOS", "version": "7.x - Minimal Install" }, { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 8.x jessie/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-8-amd64", "name": "debian-8-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "8.x jessie/Stable - Minimal Install" }, { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (amd64)", "family": "Debian GNU/Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64", "name": "debian-9-amd64", "user_data_format": "cloud_init", "vendor": "Debian", "version": "9.x Stretch/Stable - Minimal Install" }, { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Red Hat Enterprise Linux 7.x - Minimal Install (amd64)", "family": "Red Hat Enterprise Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-7-amd64", "name": "red-7-amd64", "user_data_format": "cloud_init", "vendor": "Red Hat", "version": "7.x - Minimal Install" } ], "total_count": 4 }
Retrieve an operating system
This request retrieves a single operating system specified by the name in the URL.
GET /operating_systems/{name}
Request
Path Parameters
The operating system name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/operating_system/$operating_system_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetOperatingSystemOptions{} options.SetName(osName) operatingSystem, response, err := vpcService.GetOperatingSystem(options)
GetOperatingSystemOptions getOperatingSystemOptions = new GetOperatingSystemOptions.Builder() .name(osName) .build(); Response<OperatingSystem> response = service.getOperatingSystem(getOperatingSystemOptions).execute(); OperatingSystem operatingSystem = response.getResult();
const response = await vpcService.getOperatingSystem({ name: osName });
response = service.get_operating_system(name)
Response
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
Status Code
The operating system was retrieved successfully.
An operating system with the specified name could not be found.
{ "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Red Hat Enterprise Linux 7.x - Minimal Install (amd64)", "family": "Red Hat Enterprise Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-7-amd64", "name": "red-7-amd64", "user_data_format": "cloud_init", "vendor": "Red Hat", "version": "7.x - Minimal Install" }
List all keys
This request lists all keys in the region. A key contains a public SSH key which may be installed on instances when they are created. Private keys are not stored.
GET /keys
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/keys?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listKeysOptions := &vpcv1.ListKeysOptions{} keys, response, err := vpcService.ListKeys(listKeysOptions)
ListKeysOptions listKeysOptions = new ListKeysOptions.Builder() .build(); Response<KeyCollection> response = service.listKeys(listKeysOptions).execute(); KeyCollection keyCollection = response.getResult();
const response = await vpcService.listKeys();
response = service.list_keys()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/keys?limit=20
first
Collection of keys
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/keys?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The keys were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/keys?limit=50" }, "keys": [ { "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:[...]", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/82679077-ac3b-4c10-be16-63e9c21f0f45", "id": "82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "type": "rsa" }, { "created_at": "2019-01-21T01:28:11.000Z", "crn": "crn:[...]", "fingerprint": "SHA256:XgUFJWiZbPehNHl706+mJbZdPDmSJh8G2ycvCYR2t5U", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/a9f3ae27-4769-43e3-b5a3-a2856fbad468", "id": "a9f3ae27-4769-43e3-b5a3-a2856fbad468", "length": 2048, "name": "my-key-2", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6iw94c1htpVzC33sd874W6SeTZ9pGDZdY50vsnPUpYVfuU9WDscyy/NYVR74ZvSw1vN1QK57GEW46Uhh2JdvyQ1jiMPI6amu6bHiBqnWTo3HUFPBoxM9/3j0MhspjGyrO7JK3fOwyGrnquAqRq5BPibN8JLuZwCfVyucz98hEmnf9sEphJ5ab3ywVU3echaJZBEdUNEf2ZAHGGe5qnVW33y4PmRf5q90mPkJYwjTgTjZ3fPG2lV01S3eTbHV7zr1wxW4FSTFm7dVnfTURPzKc7mL4MS35s9gX73imvZL6O9ZH54IDoB8TBhx0U5657n6MoznFeXVcFSDLLpMXf7Gr", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "type": "rsa" } ], "limit": 50, "total_count": 2 }
Create a key
This request creates a new SSH key from an key prototype object. The prototype object is structured in the same way as a retrieved key, and contains the information necessary to create the new key. The public key value must be provided.
POST /keys
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The key prototype object
A unique public SSH key to import, in OpenSSH format (consisting of three space-separated fields: the algorithm name, base64-encoded key, and a comment). The algorithm and comment fields may be omitted, as only the key field is imported.
Keys of type
rsa
may be 2048 or 4096 bits in length, however 4096 is recommended. Keys of typeed25519
are 256 bits in length.Example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En
The name for this key. The name must not be used by another key in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key
The resource group to use. If unspecified, the account's default resource group will be used.
The crypto-system used by this key
Allowable values: [
ed25519
,rsa
]Default:
rsa
curl -X POST "$vpc_api_endpoint/v1/keys?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-key-1", "public_key":"AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "type":"rsa" }'
options := &vpcv1.CreateKeyOptions{} options.SetName(name) options.SetPublicKey(publicKey) key, response, err := vpcService.CreateKey(options)
CreateKeyOptions createKeyOptions = new CreateKeyOptions.Builder() .publicKey(mySshKey) .name("my-key") .build(); Response<Key> response = service.createKey(createKeyOptions).execute(); Key key = response.getResult();
const params = { publicKey, name: 'my-key', type: 'rsa', }; const response = await vpcService.createKey(params);
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id resource_group = resource_group_identity_model # A unique public SSH key to import, encoded in PEM format. # The key (prior to encoding) must be either 2048 or 4096 bits long. public_key = 'replace with your public SSH Key' name = 'my-key' type = 'rsa' response = service.create_key( public_key, name=name, resource_group=resource_group, type=type, )
Response
The date and time that the key was created
The CRN for this key
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:a6b1a881-2ce8-41a3-80fc-36316a73f803
The fingerprint for this key. The value is returned base64-encoded and prefixed with the hash algorithm (always
SHA256
).Example:
SHA256:yxavE4CIOL2NlsqcurRO3xGjkP6m/0mp8ugojH5yxlY
The URL for this key
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/keys/a6b1a881-2ce8-41a3-80fc-36316a73f803
The unique identifier for this key
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The length of this key (in bits)
Possible values: [
2048
,256
,4096
]The name for this key. The name must not be used by another key in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key
The public SSH key, consisting of two space-separated fields: the algorithm name, and the base64-encoded key.
Example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En
The resource group for this key
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The crypto-system used by this key
Possible values: [
ed25519
,rsa
]
Status Code
The key was created successfully.
An invalid key prototype object was provided.
{ "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:[...]", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/82679077-ac3b-4c10-be16-63e9c21f0f45", "id": "82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "type": "rsa" }
Request
Path Parameters
The key identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/keys/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteKeyOptions := &vpcv1.DeleteKeyOptions{} deleteKeyOptions.SetID(id) response, err := vpcService.DeleteKey(deleteKeyOptions)
DeleteKeyOptions deleteKeyOptions = new DeleteKeyOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteKey(deleteKeyOptions).execute();
const response = await vpcService.deleteKey({id});
response = service.delete_key(id)
Retrieve a key
This request retrieves a single key specified by the identifier in the URL.
GET /keys/{id}
Request
Path Parameters
The key identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/keys/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getKeyOptions := &vpcv1.GetKeyOptions{} getKeyOptions.SetID(id) key, response, err := vpcService.GetKey(getKeyOptions)
GetKeyOptions getKeyOptions = new GetKeyOptions.Builder() .id(id) .build(); Response<Key> response = service.getKey(getKeyOptions).execute(); Key key = response.getResult();
const response = await vpcService.getKey({id});
response = service.get_key(id)
Response
The date and time that the key was created
The CRN for this key
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:a6b1a881-2ce8-41a3-80fc-36316a73f803
The fingerprint for this key. The value is returned base64-encoded and prefixed with the hash algorithm (always
SHA256
).Example:
SHA256:yxavE4CIOL2NlsqcurRO3xGjkP6m/0mp8ugojH5yxlY
The URL for this key
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/keys/a6b1a881-2ce8-41a3-80fc-36316a73f803
The unique identifier for this key
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The length of this key (in bits)
Possible values: [
2048
,256
,4096
]The name for this key. The name must not be used by another key in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key
The public SSH key, consisting of two space-separated fields: the algorithm name, and the base64-encoded key.
Example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En
The resource group for this key
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The crypto-system used by this key
Possible values: [
ed25519
,rsa
]
Status Code
The key was retrieved successfully.
A key with the specified identifier could not be found.
{ "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:[...]", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/82679077-ac3b-4c10-be16-63e9c21f0f45", "id": "82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "type": "rsa" }
Request
Path Parameters
The key identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The key patch
The name for this key. The name must not be used by another key in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key
curl -X PATCH "$vpc_api_endpoint/v1/keys/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-key-1-updated" }'
updateKeyOptions := &vpcv1.UpdateKeyOptions{} updateKeyOptions.SetID(id) updateKeyOptions.SetName(name) response, response, err := vpcService.UpdateKey(updateKeyOptions)
UpdateKeyOptions updateKeyOptions = new UpdateKeyOptions.Builder() .id(id) .name(name) .build(); Response<Key> response = service.updateKey(updateKeyOptions).execute(); Key key = response.getResult();
const response = await vpcService.updateKey({ id, name: 'my-ssh-key', });
response = service.update_key( id, name='my-key', )
Response
The date and time that the key was created
The CRN for this key
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:a6b1a881-2ce8-41a3-80fc-36316a73f803
The fingerprint for this key. The value is returned base64-encoded and prefixed with the hash algorithm (always
SHA256
).Example:
SHA256:yxavE4CIOL2NlsqcurRO3xGjkP6m/0mp8ugojH5yxlY
The URL for this key
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/keys/a6b1a881-2ce8-41a3-80fc-36316a73f803
The unique identifier for this key
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The length of this key (in bits)
Possible values: [
2048
,256
,4096
]The name for this key. The name must not be used by another key in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key
The public SSH key, consisting of two space-separated fields: the algorithm name, and the base64-encoded key.
Example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En
The resource group for this key
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The crypto-system used by this key
Possible values: [
ed25519
,rsa
]
Status Code
The key was updated successfully.
An invalid key patch was provided.
A key with the specified identifier could not be found.
{ "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:[...]", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/82679077-ac3b-4c10-be16-63e9c21f0f45", "id": "82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1-updated", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "type": "rsa" }
List all instance profiles
This request lists provisionable instance profiles in the region. An instance profile specifies the performance characteristics and pricing model for an instance.
GET /instance/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceProfilesOptions{} profiles, response, err := vpcService.ListInstanceProfiles(options)
ListInstanceProfilesOptions listInstanceProfilesOptions = new ListInstanceProfilesOptions(); Response<InstanceProfileCollection> response = service.listInstanceProfiles(listInstanceProfilesOptions).execute(); InstanceProfileCollection instanceProfileCollection = response.getResult();
const response = await vpcService.listInstanceProfiles({ id });
response = service.list_instance_profiles()
Response
Collection of virtual server instance profiles
Status Code
The instance profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles?limit=50" }, "limit": 50, "profiles": [ { "bandwidth": { "type": "fixed", "value": 4000 }, "confidential_compute_modes": { "default": "sgx", "type": "enum", "values": [ "sgx", "disabled" ] }, "disks": [], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "memory": { "type": "fixed", "value": 8 }, "name": "bx2-2x8", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 5, "min": 1, "type": "range" }, "numa_count": { "type": "dependent" }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "port_speed": { "type": "fixed", "value": 16000 }, "reservation_terms": { "type": "enum", "values": [ "one_year", "three_year" ] }, "resource_type": "instance_profile", "secure_boot_modes": { "default": false, "type": "enum", "values": [ true, false ] }, "status": "previous", "total_volume_bandwidth": { "default": 1000, "max": 3500, "min": 250, "step": 1, "type": "range" }, "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 2 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } }, { "bandwidth": { "type": "fixed", "value": 8000 }, "confidential_compute_modes": { "default": "disabled", "type": "enum", "values": [ "sgx", "disabled" ] }, "disks": [], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16", "memory": { "type": "fixed", "value": 16 }, "name": "bx2-4x16", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 5, "min": 1, "type": "range" }, "numa_count": { "type": "fixed", "value": 2 }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "port_speed": { "type": "fixed", "value": 16000 }, "reservation_terms": { "type": "enum", "values": [ "one_year", "three_year" ] }, "resource_type": "instance_profile", "secure_boot_modes": { "default": false, "type": "enum", "values": [ true, false ] }, "status": "previous", "total_volume_bandwidth": { "default": 2000, "max": 7500, "min": 250, "step": 1, "type": "range" }, "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 4 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } }, { "bandwidth": { "type": "fixed", "value": 16000 }, "confidential_compute_modes": { "default": "disabled", "type": "enum", "values": [ "sgx", "disabled" ] }, "disks": [], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-8x32", "memory": { "type": "fixed", "value": 32 }, "name": "bx2-8x32", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 5, "min": 1, "type": "range" }, "numa_count": { "type": "fixed", "value": 2 }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "port_speed": { "type": "fixed", "value": 16000 }, "reservation_terms": { "type": "enum", "values": [ "one_year", "three_year" ] }, "resource_type": "instance_profile", "secure_boot_modes": { "default": false, "type": "enum", "values": [ true, false ] }, "status": "previous", "total_volume_bandwidth": { "default": 4000, "max": 15500, "min": 250, "step": 1, "type": "range" }, "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 8 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } } ], "total_count": 3 }
Retrieve an instance profile
This request retrieves a single instance profile specified by the name in the URL.
GET /instance/profiles/{name}
Request
Path Parameters
The instance profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance/profiles/$profile_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceProfileOptions{} options.SetName(profileName) profile, response, err := vpcService.GetInstanceProfile(options)
GetInstanceProfileOptions getInstanceProfileOptions = new GetInstanceProfileOptions.Builder() .name(profileName) .build(); Response<InstanceProfile> response = service.getInstanceProfile(getInstanceProfileOptions).execute(); InstanceProfile instanceProfile = response.getResult();
const response = await vpcService.getInstanceProfile({ name: profileName });
response = service.get_instance_profile(name)
Response
Collection of the instance profile's disks
Possible values: number of items ≥ 0
The product family this virtual server instance profile belongs to
Example:
balanced
The URL for this virtual server instance profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
The resource type
Possible values: [
instance_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the instance profile:
previous
: This instance profile is an older revision, but remains provisionable and usable.current
: This profile is the latest revision.
Revisions are indicated by the generation of an instance profile. Refer to the [profile naming conventions] (https://cloud.ibm.com/docs/vpc?topic=vpc-profiles&interface=ui#profiles-naming-rule) for information on how generations are defined within an instance profile.
The enumerated values for this property may expand in the future.
Possible values: [
current
,previous
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
current
Status Code
The instance profile was retrieved successfully
An instance profile with the specified name could not be found.
{ "bandwidth": { "type": "fixed", "value": 16000 }, "confidential_compute_modes": { "default": "disabled", "type": "enum", "values": [ "sgx", "disabled" ] }, "disks": [], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-8x32", "memory": { "type": "fixed", "value": 32 }, "name": "bx2-8x32", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 5, "min": 1, "type": "range" }, "numa_count": { "type": "fixed", "value": 2 }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "port_speed": { "type": "fixed", "value": 16000 }, "reservation_terms": { "type": "enum", "values": [ "one_year", "three_year" ] }, "resource_type": "instance_profile", "secure_boot_modes": { "default": false, "type": "enum", "values": [ true, false ] }, "status": "previous", "total_volume_bandwidth": { "default": 4000, "max": 15500, "min": 250, "step": 1, "type": "range" }, "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 8 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } }
List all instance templates
This request lists all instance templates in the region.
GET /instance/templates
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance/templates?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceTemplatesOptions{} instanceTemplates, response, err := vpcService.ListInstanceTemplates(options)
ListInstanceTemplatesOptions listInstanceTemplatesOptions = new ListInstanceTemplatesOptions(); Response<InstanceTemplateCollection> response = service.listInstanceTemplates(listInstanceTemplatesOptions).execute(); InstanceTemplateCollection instanceTemplateCollection = response.getResult();
const response = await vpcService.listInstanceTemplates();
response = service.list_instance_templates()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of instance templates
templates
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance templates were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/templates?limit=50" }, "limit": 50, "templates": [ { "boot_volume_attachment": { "delete_volume_on_instance_delete": false, "name": "volume-attachment", "volume": { "capacity": 100, "name": "my-instance-template-2-boot", "profile": { "name": "general-purpose" } } }, "created_at": "2020-10-01T13:37:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/templates/07a7-3eb3a95b-997c-4108-a108-8f68f30f1d21", "id": "07a7-3eb3a95b-997c-4108-a108-8f68f30f1d21", "image": { "id": "r018-6f153a5d-6a9a-496d-8063-5c39932f6ded" }, "keys": [ { "id": "r018-176f38a6-5d21-4cfb-ac20-f20d90d9e888" } ], "name": "my-instance-template-2", "primary_network_interface": { "security_groups": [ { "id": "r018-f4793b96-4fc1-4a57-a18d-ff50d8001566" } ], "subnet": { "id": "07a7-3162c0fc-178f-46da-b4ca-d9448824056c" } }, "profile": { "name": "bx2-2x8" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "vpc": { "id": "r018-d6979555-bf41-4755-ab78-f1f753a939e0" }, "zone": { "name": "us-south-3" } } ], "total_count": 1 }
Create an instance template
This request creates a new instance template. The prototype object is structured in the same way as a retrieved instance template, and contains the information necessary to provision a new instance from the template.
If a source_template
is specified in the prototype object, its contents are copied into
the new template prior to copying any other properties provided in the prototype object.
POST /instance/templates
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance template prototype object
The availability policy to use for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Allowable values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
restart
availability_policy
The confidential compute mode to use for this virtual server instance. If the value
sgx
is specified,reservation_affinity.policy
must bedisabled
.If unspecified, the default confidential compute mode from the profile will be used.
Allowable values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The default trusted profile configuration to use for this virtual server instance
This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property.
The default IAM trusted profile to use for this virtual server instance
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
target
If set to
true
, the system will create a link to the specifiedtarget
trusted profile during instance 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 instance is deleted.Default:
true
default_trusted_profile
Indicates whether secure boot is enabled for this virtual server instance.
If unspecified, the default secure boot mode from the profile will be used.
The public SSH keys for the administrative user of the virtual server instance. Keys will be made available to the virtual server instance as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the administrative user.
For Windows images, the keys of type
rsa
must be specified, and one will be selected to encrypt the administrator password. Keys are optional for other images, but if no keys are specified, the instance will be inaccessible unless the specified image provides another means of access.This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property
Possible values: number of items ≤ 10, contains only unique items
Examples:Viewkeys
The metadata service configuration
The name for this instance template. The name must not be used by another instance template in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance
The placement restrictions to use for the virtual server instance.
If specified,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance.
If unspecified,
bx2-2x8
will be used, but this default value is expected to change in the future.The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The resource group to use. If unspecified, the account's default resource group will be used.
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
User data to make available when setting up the virtual server instance.
Possible values: 0 ≤ length ≤ 65536
Default:
The additional volume attachments to create for the virtual server instance
Possible values: 0 ≤ number of items ≤ 12
The VPC this virtual server instance will reside in.
If specified, it must match the VPC for the subnets of the instance network attachments or instance network interfaces.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Create an instance template that creates instances by using an image.
The image's
user_data_format
must becloud_init
.The image to use when provisioning the virtual server instance.
The zone this virtual server instance will reside in
The boot volume attachment to create for the virtual server instance
A prototype object for a new volume
The profile to use for this volume.
The capacity to use for the volume (in gigabytes). The specified value must be at least the image's
minimum_provisioned_size
, and must be within theboot_capacity
range of the volume's profile.If unspecified, the capacity will be the image's
minimum_provisioned_size
.Possible values: value ≤ 250
Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, and the image is encrypted, the image's
encryption_key
will be used. Otherwise, theencryption
type for the volume will beprovider_managed
.Examples:ViewThe maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use for this volume. If unspecified, the instance's resource group will be used.
volume
Indicates whether deleting the instance will also delete the attached volume
Default:
true
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
boot_volume_attachment
One of
curl -X POST "$vpc_api_endpoint/v1/instance/templates?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "primary_network_interface": { "subnet": { "id": "0d933c75-492a-4756-9832-1200585dfa79" } }, "name": "my-instance-template", "zone": { "name": "us-south-1" }, "vpc": { "id": "dc201ab2-8536-4904-86a8-084d84582133" }, "profile": { "name": "bx2-2x8" }, "image": { "id": "3f9a2d96-830e-4100-9b4c-663225a3f872" }, "keys": [ { "id": "363f6d70-0000-0001-0000-00000013b96c" } ] }'
options := &vpcv1.CreateInstanceTemplateOptions{} options.SetInstanceTemplatePrototype(&vpcv1.InstanceTemplatePrototype{ Name: &name, Image: &vpcv1.ImageIdentity{ ID: &imageID, }, Profile: &vpcv1.InstanceProfileIdentity{ Name: &profileName, }, Zone: &vpcv1.ZoneIdentity{ Name: &zoneName, }, PrimaryNetworkInterface: &vpcv1.NetworkInterfacePrototype{ Subnet: &vpcv1.SubnetIdentity{ ID: &subnetId, }, }, Keys: []vpcv1.KeyIdentityIntf{ &vpcv1.KeyIdentity{ ID: &keyID, }, }, VPC: &vpcv1.VPCIdentity{ ID: &vpcID, }, }) instanceTemplate, response, err = vpcService.CreateInstanceTemplate(options)
KeyIdentityById keyIdentityModel = new KeyIdentityById.Builder() .id(keyId) .build(); InstanceProfileIdentityByName instanceProfileIdentityModel = new InstanceProfileIdentityByName.Builder() .name(profileName) .build(); VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); NetworkInterfacePrototype networkInterfacePrototypeModel = new NetworkInterfacePrototype.Builder() .subnet(subnetIdentityModel) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); ImageIdentityById imageIdentityModel = new ImageIdentityById.Builder() .id(imageId) .build(); InstanceTemplatePrototypeInstanceByImage instanceTemplatePrototypeModel = new InstanceTemplatePrototypeInstanceByImage.Builder() .name("my-instance-template") .keys(new java.util.ArrayList<KeyIdentity>(java.util.Arrays.asList(keyIdentityModel))) .profile(instanceProfileIdentityModel) .vpc(vpcIdentityModel) .primaryNetworkInterface(networkInterfacePrototypeModel) .zone(zoneIdentityModel) .image(imageIdentityModel) .build(); CreateInstanceTemplateOptions createInstanceTemplateOptions = new CreateInstanceTemplateOptions.Builder() .instanceTemplatePrototype(instanceTemplatePrototypeModel) .build(); Response<InstanceTemplate> response = service.createInstanceTemplate(createInstanceTemplateOptions).execute(); InstanceTemplate instanceTemplate = response.getResult();
const subnetIdentityModel = { id: subnetID, }; const networkInterfacePrototypeModel = { name: 'my-network-interface', subnet: subnetIdentityModel, }; const instanceProfileIdentityModel = { name: instanceProfileName, }; const vpcIdentityModel = { id: vpcID, }; const zoneIdentityModel = { name: zoneName, }; const imageIdentityModel = { id: imageID, }; const instanceTemplatePrototypeModel = { name: 'my-instance-template', profile: instanceProfileIdentityModel, vpc: vpcIdentityModel, primary_network_interface: networkInterfacePrototypeModel, zone: zoneIdentityModel, image: imageIdentityModel, }; const params = { instanceTemplatePrototype: instanceTemplatePrototypeModel, }; const response = await vpcService.createInstanceTemplate(params);
encryption_key_identity_model = {} encryption_key_identity_model[ 'crn'] = key_crn volume_profile_identity_model = {} volume_profile_identity_model['name'] = 'general-purpose' security_group_identity_model = {} security_group_identity_model[ 'id'] = security_group_id subnet_identity_model = {} subnet_identity_model['id'] = subnet_id volume_attachment_prototype_instance_context_volume_model = {} volume_attachment_prototype_instance_context_volume_model[ 'id'] = data_volume_id volume_prototype_instance_by_image_context_model = {} volume_prototype_instance_by_image_context_model['name'] = 'my-volume' volume_prototype_instance_by_image_context_model['profile'] = volume_profile_identity_model volume_prototype_instance_by_image_context_model[ 'encryption_key'] = encryption_key_identity_model volume_prototype_instance_by_image_context_model['capacity'] = 100 volume_prototype_instance_by_image_context_model['iops'] = 10000 image_identity_model = {} image_identity_model['id'] = image_id instance_profile_identity_model = {} instance_profile_identity_model['name'] = 'bc1-4x16' key_identity_model = {} key_identity_model['id'] = ssh_key_id network_interface_prototype_model = {} network_interface_prototype_model['name'] = 'my-network-interface' network_interface_prototype_model['security_groups'] = [ security_group_identity_model ] network_interface_prototype_model['subnet'] = subnet_identity_model resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id vpc_identity_model = {} vpc_identity_model['id'] = vpc_id volume_attachment_prototype_instance_by_image_context_model = {} volume_attachment_prototype_instance_by_image_context_model[ 'delete_volume_on_instance_delete'] = True volume_attachment_prototype_instance_by_image_context_model[ 'name'] = 'my-volume-attachment' volume_attachment_prototype_instance_by_image_context_model[ 'volume'] = volume_prototype_instance_by_image_context_model volume_attachment_prototype_instance_context_model = {} volume_attachment_prototype_instance_context_model[ 'delete_volume_on_instance_delete'] = True volume_attachment_prototype_instance_context_model[ 'name'] = 'my-volume-attachment' volume_attachment_prototype_instance_context_model[ 'volume'] = volume_attachment_prototype_instance_context_volume_model zone_identity_model = {} zone_identity_model['name'] = zone_name instance_template_prototype_model = {} instance_template_prototype_model['name'] = 'my-instance-template' instance_template_prototype_model['keys'] = [key_identity_model] instance_template_prototype_model['network_interfaces'] = [ network_interface_prototype_model ] instance_template_prototype_model['profile'] = instance_profile_identity_model instance_template_prototype_model['user_data'] = 'user-data' instance_template_prototype_model['volume_attachments'] = [ volume_attachment_prototype_instance_context_model ] instance_template_prototype_model['vpc'] = vpc_identity_model instance_template_prototype_model[ 'resource_group'] = resource_group_identity_model instance_template_prototype_model[ 'primary_network_interface'] = network_interface_prototype_model instance_template_prototype_model['zone'] = zone_identity_model instance_template_prototype_model[ 'boot_volume_attachment'] = volume_attachment_prototype_instance_by_image_context_model instance_template_prototype_model['image'] = image_identity_model response = service.create_instance_template(instance_template_prototype)
Response
The date and time that the instance template was created
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
The resource group for this instance template
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The availability policy to use for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The confidential compute mode to use for this virtual server instance. If the value
sgx
is specified,reservation_affinity.policy
must bedisabled
.If unspecified, the default confidential compute mode from the profile will be used.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The default trusted profile configuration to use for this virtual server instance
This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property.
The default IAM trusted profile to use for this virtual server instance
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
target
If set to
true
, the system will create a link to the specifiedtarget
trusted profile during instance 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 instance is deleted.
default_trusted_profile
Indicates whether secure boot is enabled for this virtual server instance.
If unspecified, the default secure boot mode from the profile will be used.
The public SSH keys for the administrative user of the virtual server instance. Keys will be made available to the virtual server instance as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the administrative user.
For Windows images, the keys of type
rsa
must be specified, and one will be selected to encrypt the administrator password. Keys are optional for other images, but if no keys are specified, the instance will be inaccessible unless the specified image provides another means of access.This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property
Possible values: number of items ≤ 10, contains only unique items
Examples:Viewkeys
The metadata service configuration
The placement restrictions to use for the virtual server instance.
If specified,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance.
If unspecified,
bx2-2x8
will be used, but this default value is expected to change in the future.The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
User data to make available when setting up the virtual server instance.
Possible values: 0 ≤ length ≤ 65536
The additional volume attachments to create for the virtual server instance
Possible values: 0 ≤ number of items ≤ 12
The VPC this virtual server instance will reside in.
If specified, it must match the VPC for the subnets of the instance network attachments or instance network interfaces.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Create an instance by using an image.
The image to use when provisioning the virtual server instance.
The zone this virtual server instance will reside in
The boot volume attachment to create for the virtual server instance
A prototype object for a new volume
The profile to use for this volume.
The capacity to use for the volume (in gigabytes). The specified value must be at least the image's
minimum_provisioned_size
, and must be within theboot_capacity
range of the volume's profile.If unspecified, the capacity will be the image's
minimum_provisioned_size
.Possible values: value ≤ 250
Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, and the image is encrypted, the image's
encryption_key
will be used. Otherwise, theencryption
type for the volume will beprovider_managed
.Examples:ViewThe maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use for this volume. If unspecified, the instance's resource group will be used.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000
volume
Indicates whether deleting the instance will also delete the attached volume
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
boot_volume_attachment
One of
Status Code
The instance template was created successfully.
An invalid instance template prototype object was provided.
{ "boot_volume_attachment": { "delete_volume_on_instance_delete": true, "name": "volume-attachment", "volume": { "capacity": 100, "name": "my-instance-template-boot", "profile": { "name": "general-purpose" } } }, "created_at": "2020-10-01T13:37:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "image": { "id": "r018-6f153a5d-6a9a-496d-8063-5c39932f6ded" }, "keys": [ { "id": "r018-176f38a6-5d21-4cfb-ac20-f20d90d9e888" } ], "name": "my-instance-template", "primary_network_interface": { "security_groups": [ { "id": "r018-f4793b96-4fc1-4a57-a18d-ff50d8001566" } ], "subnet": { "id": "07a7-3162c0fc-178f-46da-b4ca-d9448824056c" } }, "profile": { "name": "bx2-2x8" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "vpc": { "id": "r018-d6979555-bf41-4755-ab78-f1f753a939e0" }, "zone": { "name": "us-south-3" } }
Delete an instance template
This request deletes the instance template. This operation cannot be reversed.
DELETE /instance/templates/{id}
Request
Path Parameters
The instance template identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance/templates/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceTemplateOptions{} options.SetID(id) response, err := vpcService.DeleteInstanceTemplate(options)
DeleteInstanceTemplateOptions deleteInstanceTemplateOptions = new DeleteInstanceTemplateOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteInstanceTemplate(deleteInstanceTemplateOptions).execute();
const response = await vpcService.deleteInstanceTemplate({ id });
response = service.delete_instance_template(id)
Retrieve an instance template
This request retrieves a single instance template specified by the identifier in the URL.
GET /instance/templates/{id}
Request
Path Parameters
The instance template identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance/templates/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceTemplateOptions{} options.SetID(id) instanceTemplate, response, err := vpcService.GetInstanceTemplate(options)
GetInstanceTemplateOptions getInstanceTemplateOptions = new GetInstanceTemplateOptions.Builder() .id(id) .build(); Response<InstanceTemplate> response = service.getInstanceTemplate(getInstanceTemplateOptions).execute(); InstanceTemplate instanceTemplate = response.getResult();
const response = await vpcService.getInstanceTemplate({ id });
response = service.get_instance_template(id)
Response
The date and time that the instance template was created
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
The resource group for this instance template
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The availability policy to use for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The confidential compute mode to use for this virtual server instance. If the value
sgx
is specified,reservation_affinity.policy
must bedisabled
.If unspecified, the default confidential compute mode from the profile will be used.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The default trusted profile configuration to use for this virtual server instance
This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property.
The default IAM trusted profile to use for this virtual server instance
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
target
If set to
true
, the system will create a link to the specifiedtarget
trusted profile during instance 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 instance is deleted.
default_trusted_profile
Indicates whether secure boot is enabled for this virtual server instance.
If unspecified, the default secure boot mode from the profile will be used.
The public SSH keys for the administrative user of the virtual server instance. Keys will be made available to the virtual server instance as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the administrative user.
For Windows images, the keys of type
rsa
must be specified, and one will be selected to encrypt the administrator password. Keys are optional for other images, but if no keys are specified, the instance will be inaccessible unless the specified image provides another means of access.This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property
Possible values: number of items ≤ 10, contains only unique items
Examples:Viewkeys
The metadata service configuration
The placement restrictions to use for the virtual server instance.
If specified,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance.
If unspecified,
bx2-2x8
will be used, but this default value is expected to change in the future.The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
User data to make available when setting up the virtual server instance.
Possible values: 0 ≤ length ≤ 65536
The additional volume attachments to create for the virtual server instance
Possible values: 0 ≤ number of items ≤ 12
The VPC this virtual server instance will reside in.
If specified, it must match the VPC for the subnets of the instance network attachments or instance network interfaces.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Create an instance by using an image.
The image to use when provisioning the virtual server instance.
The zone this virtual server instance will reside in
The boot volume attachment to create for the virtual server instance
A prototype object for a new volume
The profile to use for this volume.
The capacity to use for the volume (in gigabytes). The specified value must be at least the image's
minimum_provisioned_size
, and must be within theboot_capacity
range of the volume's profile.If unspecified, the capacity will be the image's
minimum_provisioned_size
.Possible values: value ≤ 250
Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, and the image is encrypted, the image's
encryption_key
will be used. Otherwise, theencryption
type for the volume will beprovider_managed
.Examples:ViewThe maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use for this volume. If unspecified, the instance's resource group will be used.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000
volume
Indicates whether deleting the instance will also delete the attached volume
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
boot_volume_attachment
One of
Status Code
The instance template was retrieved successfully.
An instance template with the specified identifier could not be found.
{ "boot_volume_attachment": { "delete_volume_on_instance_delete": true, "name": "volume-attachment", "volume": { "capacity": 100, "name": "my-instance-template-boot", "profile": { "name": "general-purpose" } } }, "created_at": "2020-10-01T13:37:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "image": { "id": "r018-6f153a5d-6a9a-496d-8063-5c39932f6ded" }, "keys": [ { "id": "r018-176f38a6-5d21-4cfb-ac20-f20d90d9e888" } ], "name": "my-instance-template", "primary_network_interface": { "security_groups": [ { "id": "r018-f4793b96-4fc1-4a57-a18d-ff50d8001566" } ], "subnet": { "id": "07a7-3162c0fc-178f-46da-b4ca-d9448824056c" } }, "profile": { "name": "bx2-2x8" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "vpc": { "id": "r018-d6979555-bf41-4755-ab78-f1f753a939e0" }, "zone": { "name": "us-south-3" } }
Update an instance template
This request updates an instance template with the information provided in the instance template patch. The instance template patch object is structured in the same way as a retrieved instance template and contains only the information to be updated.
PATCH /instance/templates/{id}
Request
Path Parameters
The instance template identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance template patch
The name for this instance template. The name must not be used by another instance template in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-template
curl -X PATCH "$vpc_api_endpoint/v1/instance/templates/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-template" }'
options := &vpcv1.UpdateInstanceTemplateOptions{} options.SetID(id) options.SetName(name) instanceTemplate, response, err := vpcService.UpdateInstanceTemplate(options)
UpdateInstanceTemplateOptions updateInstanceTemplateOptions = new UpdateInstanceTemplateOptions.Builder() .id(id) .name(name) .build(); Response<InstanceTemplate> response = service.updateInstanceTemplate(updateInstanceTemplateOptions).execute(); InstanceTemplate instanceTemplate = response.getResult();
const response = await vpcService.updateInstanceTemplate({ id, name: 'my-instance-template', });
response = service.update_instance_template(id, name=new_name)
Response
The date and time that the instance template was created
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
The resource group for this instance template
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The availability policy to use for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The confidential compute mode to use for this virtual server instance. If the value
sgx
is specified,reservation_affinity.policy
must bedisabled
.If unspecified, the default confidential compute mode from the profile will be used.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The default trusted profile configuration to use for this virtual server instance
This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property.
The default IAM trusted profile to use for this virtual server instance
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
target
If set to
true
, the system will create a link to the specifiedtarget
trusted profile during instance 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 instance is deleted.
default_trusted_profile
Indicates whether secure boot is enabled for this virtual server instance.
If unspecified, the default secure boot mode from the profile will be used.
The public SSH keys for the administrative user of the virtual server instance. Keys will be made available to the virtual server instance as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the administrative user.
For Windows images, the keys of type
rsa
must be specified, and one will be selected to encrypt the administrator password. Keys are optional for other images, but if no keys are specified, the instance will be inaccessible unless the specified image provides another means of access.This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property
Possible values: number of items ≤ 10, contains only unique items
Examples:Viewkeys
The metadata service configuration
The placement restrictions to use for the virtual server instance.
If specified,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance.
If unspecified,
bx2-2x8
will be used, but this default value is expected to change in the future.The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
User data to make available when setting up the virtual server instance.
Possible values: 0 ≤ length ≤ 65536
The additional volume attachments to create for the virtual server instance
Possible values: 0 ≤ number of items ≤ 12
The VPC this virtual server instance will reside in.
If specified, it must match the VPC for the subnets of the instance network attachments or instance network interfaces.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Create an instance by using an image.
The image to use when provisioning the virtual server instance.
The zone this virtual server instance will reside in
The boot volume attachment to create for the virtual server instance
A prototype object for a new volume
The profile to use for this volume.
The capacity to use for the volume (in gigabytes). The specified value must be at least the image's
minimum_provisioned_size
, and must be within theboot_capacity
range of the volume's profile.If unspecified, the capacity will be the image's
minimum_provisioned_size
.Possible values: value ≤ 250
Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, and the image is encrypted, the image's
encryption_key
will be used. Otherwise, theencryption
type for the volume will beprovider_managed
.Examples:ViewThe maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use for this volume. If unspecified, the instance's resource group will be used.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000
volume
Indicates whether deleting the instance will also delete the attached volume
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
boot_volume_attachment
One of
Status Code
The instance template was updated successfully.
An invalid instance template patch was provided.
An instance template with the specified identifier could not be found.
{ "boot_volume_attachment": { "delete_volume_on_instance_delete": true, "name": "volume-attachment", "volume": { "capacity": 100, "name": "my-instance-template-boot", "profile": { "name": "general-purpose" } } }, "created_at": "2020-10-01T13:37:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "image": { "id": "r018-6f153a5d-6a9a-496d-8063-5c39932f6ded" }, "keys": [ { "id": "r018-176f38a6-5d21-4cfb-ac20-f20d90d9e888" } ], "name": "my-instance-template", "primary_network_interface": { "name": "eth0", "security_groups": [ { "id": "r018-f4793b96-4fc1-4a57-a18d-ff50d8001566" } ], "subnet": { "id": "07a7-3162c0fc-178f-46da-b4ca-d9448824056c" } }, "profile": { "name": "bx2-2x8" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "vpc": { "id": "r018-d6979555-bf41-4755-ab78-f1f753a939e0" }, "zone": { "name": "us-south-3" } }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
dedicated_host.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
dedicated_host.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:1e09281b-f177-46fb-baf1-bc152b2e391a
Filters the collection to resources with a
dedicated_host.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dedicated-host
Filters the collection to resources with a
placement_target.id
property matching the specified placement group identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
placement_target.crn
property matching the specified placement group CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r018-418fe842-a3e9-47b9-a938-1aa5bd632871
Filters the collection to resources with a
placement_target.name
property matching the exact specified placement group name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
Filters the collection to resources with a
reservation.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
reservation.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
Filters the collection to resources with a
reservation.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
curl -X GET "$vpc_api_endpoint/v1/instances?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstancesOptions{} instances, response, err := vpcService.ListInstances(options)
ListInstancesOptions listInstancesOptions = new ListInstancesOptions.Builder() .build(); Response<InstanceCollection> response = service.listInstances(listInstancesOptions).execute(); InstanceCollection instanceCollection = response.getResult();
const response = await vpcService.listInstances();
response = service.list_instances()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances?limit=20
first
Collection of virtual server instances
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instances were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances?limit=20" }, "instances": [ { "availability_policy": { "host_failure": "restart" }, "bandwidth": 4000, "boot_volume_attachment": { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, "confidential_compute_mode": "sgx", "created_at": "2020-03-26T16:11:57Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "dedicated_host": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "disks": [], "enable_secure_boot": true, "health_reasons": [], "health_state": "ok", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "image": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "name": "my-image", "resource_type": "image" }, "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 8, "metadata_service": { "enabled": true, "protocol": "http", "response_hop_limit": 1 }, "name": "my-instance", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "numa_count": 2, "placement_target": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16", "name": "bx2-4x16", "resource_type": "instance_profile" }, "reservation_affinity": { "policy": "disabled", "pool": [] }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "instance", "startable": true, "status": "running", "status_reasons": [], "total_network_bandwidth": 3000, "total_volume_bandwidth": 1000, "vcpu": { "architecture": "amd64", "count": 2, "manufacturer": "intel" }, "volume_attachments": [ { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, { "device": { "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "name": "my-volume-attachment-2", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "name": "my-volume-2", "resource_type": "volume" } } ], "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "limit": 20, "next": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances?start=a977a97fae634c4da1470691cbc4c4a1&limit=20" }, "total_count": 1 }
Create an instance
This request provisions a new instance from an instance prototype object. The prototype object is structured in the same way as a retrieved instance, and contains the information necessary to provision the new instance. The instance is automatically started.
POST /instances
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.instance.create
is.instance.network-attachment.create
Generated for each instance network attachment created
is.instance.network-interface.create
Generated for each instance network interface created
is.instance.network-interface.attach
Generated for each resource being attached to an instance network interface:
- reserved IPs
- security groups
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to:
- an instance network interface, or
- a virtual network interface
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.security-group.security-group.attach
Generated for each security group being attached to:
- an instance network interface, or
- a new virtual network interface
is.subnet.subnet.update
Generated for each reserved IP created
is.virtual-network-interface.virtual-network-interface.create
Generated for each virtual network interface created
is.virtual-network-interface.virtual-network-interface.attach
Generated for:
- each virtual network interface being attached to an instance network attachment
- each virtual network interface for each reserved IP being attached to it
- each virtual network interface for each security group being attached to it
is.instance.network-attachment.attach
Generated for each virtual network interface being attached to an instance network attachment
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance prototype object
The availability policy to use for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Allowable values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
restart
availability_policy
The confidential compute mode to use for this virtual server instance. If the value
sgx
is specified,reservation_affinity.policy
must bedisabled
.If unspecified, the default confidential compute mode from the profile will be used.
Allowable values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The default trusted profile configuration to use for this virtual server instance
This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property.
The default IAM trusted profile to use for this virtual server instance
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
target
If set to
true
, the system will create a link to the specifiedtarget
trusted profile during instance 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 instance is deleted.Default:
true
default_trusted_profile
Indicates whether secure boot is enabled for this virtual server instance.
If unspecified, the default secure boot mode from the profile will be used.
The public SSH keys for the administrative user of the virtual server instance. Keys will be made available to the virtual server instance as cloud-init vendor data. For cloud-init enabled images, these keys will also be added as SSH authorized keys for the administrative user.
For Windows images, the keys of type
rsa
must be specified, and one will be selected to encrypt the administrator password. Keys are optional for other images, but if no keys are specified, the instance will be inaccessible unless the specified image provides another means of access.This property's value is used when provisioning the virtual server instance, but not subsequently managed. Accordingly, it is reflected as an instance initialization property
Possible values: number of items ≤ 10, contains only unique items
Examples:Viewkeys
The metadata service configuration
The name for this virtual server instance. The name must not be used by another virtual server instance 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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance
The placement restrictions to use for the virtual server instance.
If specified,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance.
If unspecified,
bx2-2x8
will be used, but this default value is expected to change in the future.The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The resource group to use. If unspecified, the account's default resource group will be used.
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
User data to make available when setting up the virtual server instance.
Possible values: 0 ≤ length ≤ 65536
Default:
The additional volume attachments to create for the virtual server instance
Possible values: 0 ≤ number of items ≤ 12
The VPC this virtual server instance will reside in.
If specified, it must match the VPC for the subnets of the instance network attachments or instance network interfaces.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Create an instance template that creates instances by using an image.
The image's
user_data_format
must becloud_init
.The image to use when provisioning the virtual server instance.
The zone this virtual server instance will reside in
The boot volume attachment to create for the virtual server instance
A prototype object for a new volume
The profile to use for this volume.
The capacity to use for the volume (in gigabytes). The specified value must be at least the image's
minimum_provisioned_size
, and must be within theboot_capacity
range of the volume's profile.If unspecified, the capacity will be the image's
minimum_provisioned_size
.Possible values: value ≤ 250
Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, and the image is encrypted, the image's
encryption_key
will be used. Otherwise, theencryption
type for the volume will beprovider_managed
.Examples:ViewThe maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use for this volume. If unspecified, the instance's resource group will be used.
volume
Indicates whether deleting the instance will also delete the attached volume
Default:
true
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
boot_volume_attachment
One of
curl -X POST "$vpc_api_endpoint/v1/instances?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "boot_volume_attachment": { "volume": { "encryption_key": { "crn": "crn:[...]" }, "name": "my-boot-volume", "profile": { "name": "general-purpose" } } }, "image": { "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366" }, "keys": [ { "id": "363f6d70-0000-0001-0000-00000013b96c" } ], "name": "my-instance", "placement_target": { "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221" }, "primary_network_interface": { "name": "my-network-interface", "subnet": { "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4" } }, "profile": { "name": "bx2-2x8" }, "volume_attachments": [ { "volume": { "capacity": 1000, "encryption_key": { "crn": "crn:[...]" }, "name": "my-data-volume", "profile": { "name": "5iops-tier" } } } ], "vpc": { "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f" }, "zone": { "name": "us-south-1" } }'
options := &vpcv1.CreateInstanceOptions{} options.SetInstancePrototype(&vpcv1.InstancePrototype{ Name: &name, Image: &vpcv1.ImageIdentity{ ID: &imageID, }, Profile: &vpcv1.InstanceProfileIdentity{ Name: &profileName, }, Zone: &vpcv1.ZoneIdentity{ Name: &zoneName, }, PrimaryNetworkInterface: &vpcv1.NetworkInterfacePrototype{ Subnet: &vpcv1.SubnetIdentity{ ID: &subnetId, }, }, Keys: []vpcv1.KeyIdentityIntf{ &vpcv1.KeyIdentity{ ID: &keyID, }, }, VPC: &vpcv1.VPCIdentity{ ID: &vpcID, }, }) instance, response, err = vpcService.CreateInstance(options)
KeyIdentityById keyIdentityModel = new KeyIdentityById.Builder() .id(keyId) .build(); InstanceProfileIdentityByName instanceProfileIdentityModel = new InstanceProfileIdentityByName.Builder() .name(profileName) .build(); VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); NetworkInterfacePrototype networkInterfacePrototypeModel = new NetworkInterfacePrototype.Builder() .subnet(subnetIdentityModel) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); ImageIdentityById imageIdentityModel = new ImageIdentityById.Builder() .id(imageId) .build(); InstancePrototypeInstanceByImage instancePrototypeModel = new InstancePrototypeInstanceByImage.Builder() .name("my-instance") .keys(new java.util.ArrayList<KeyIdentity>(java.util.Arrays.asList(keyIdentityModel))) .profile(instanceProfileIdentityModel) .vpc(vpcIdentityModel) .primaryNetworkInterface(networkInterfacePrototypeModel) .zone(zoneIdentityModel) .image(imageIdentityModel) .build(); CreateInstanceOptions createInstanceOptions = new CreateInstanceOptions.Builder() .instancePrototype(instancePrototypeModel) .build(); Response<Instance> response = service.createInstance(createInstanceOptions).execute(); Instance instance = response.getResult();
const subnetIdentityModel = { id: subnetId, }; const networkInterfacePrototypeModel = { name: 'my-network-interface', subnet: subnetIdentityModel, }; const instanceProfileIdentityModel = { name: instanceProfileName, }; const vpcIdentityModel = { id: vpcId, }; const zoneIdentityModel = { name: zoneName, }; const imageIdentityModel = { id: imageId, }; const instancePrototype = { name: 'my-instance', profile: instanceProfileIdentityModel, vpc: vpcIdentityModel, primary_network_interface: networkInterfacePrototypeModel, zone: zoneIdentityModel, image: imageIdentityModel, }; const response = await vpcService.createInstance(instancePrototype);
encryption_key_identity_model = {} encryption_key_identity_model['crn'] = my_key_crn volume_profile_identity_model = {} volume_profile_identity_model['name'] = 'general-purpose' security_group_identity_model = {} security_group_identity_model['id'] = security_group_id subnet_identity_model = {} subnet_identity_model['id'] = subnet_id volume_attachment_prototype_instance_context_volume_model = {} volume_attachment_prototype_instance_context_volume_model['id'] = volume_id volume_prototype_instance_by_image_context_model = {} volume_prototype_instance_by_image_context_model['capacity'] = 100 volume_prototype_instance_by_image_context_model['iops'] = 10000 volume_prototype_instance_by_image_context_model['name'] = 'my-volume' volume_prototype_instance_by_image_context_model[ 'profile'] = volume_profile_identity_model image_identity_model = {} image_identity_model['id'] = image instance_profile_identity_model = {} instance_profile_identity_model['name'] = profile key_identity_model = {} key_identity_model['id'] = my_key_id network_interface_prototype_model = {} network_interface_prototype_model['name'] = 'my-network-interface' network_interface_prototype_model['primary_ipv4_address'] = '10.0.0.5' network_interface_prototype_model['security_groups'] = [ security_group_identity_model ] network_interface_prototype_model['subnet'] = subnet_identity_model resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id vpc_identity_model = {} vpc_identity_model['id'] = vpc_id volume_attachment_prototype_instance_by_image = {} volume_attachment_prototype_instance_by_image[ 'delete_volume_on_instance_delete'] = True volume_attachment_prototype_instance_by_image[ 'name'] = 'my-volume-attachment' volume_attachment_prototype_instance_by_image[ 'volume'] = volume_prototype_instance_by_image_context_model volume_attachment_prototype_instance_context_model = {} volume_attachment_prototype_instance_context_model[ 'delete_volume_on_instance_delete'] = True volume_attachment_prototype_instance_context_model[ 'name'] = 'my-volume-attachment' volume_attachment_prototype_instance_context_model[ 'volume'] = volume_attachment_prototype_instance_context_volume_model zone_identity_model = {} zone_identity_model['name'] = zoneName instance_prototype_model = {} instance_prototype_model['keys'] = [key_identity_model] instance_prototype_model['name'] = 'my-instance' instance_prototype_model['network_interfaces'] = [ network_interface_prototype_model ] instance_prototype_model['profile'] = instance_profile_identity_model instance_prototype_model[ 'resource_group'] = resource_group_identity_model instance_prototype_model['user_data'] = 'testString' instance_prototype_model['volume_attachments'] = [ volume_attachment_prototype_instance_context_model ] instance_prototype_model['vpc'] = vpc_identity_model instance_prototype_model[ 'boot_volume_attachment'] = volume_attachment_prototype_instance_by_image instance_prototype_model['image'] = image_identity_model instance_prototype_model[ 'primary_network_interface'] = network_interface_prototype_model instance_prototype_model['zone'] = zone_identity_model instance_prototype = instance_prototype_model response = service.create_instance(instance_prototype)
Response
The availability policy for this virtual server instance
The action to perform if the compute host experiences a failure:
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
The enumerated values for this property may expand in the future.
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The total bandwidth (in megabits per second) shared across the instance network attachments or instance network interfaces and storage volumes of the virtual server instance
Example:
1000
Boot volume attachment
Examples:ViewThe URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
boot_volume_attachment
The confidential compute mode for this virtual server instance.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the virtual server instance was created
The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The instance disks for this virtual server instance.
Possible values: number of items ≥ 0
Indicates whether secure boot is enabled for this virtual server instance.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the virtual server instance.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 512
Example:
8
The metadata service configuration
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
The network attachments for this virtual server instance, including the primary network attachment.
Possible values: number of items ≥ 0, contains only unique items
The network interfaces for this instance, including the primary network interface.
If this instance has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
Possible values: number of items ≥ 1, contains only unique items
The primary network interface for this virtual server instance.
If this instance has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.
Examples:ViewThe URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this virtual server instance
Examples:ViewThe URL for this virtual server instance profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
The resource type
Possible values: [
instance_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this instance
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether the state of the virtual server instance permits a start request.
The status of the virtual server instance.
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,pending
,restarting
,running
,starting
,stopped
,stopping
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The amount of bandwidth (in megabits per second) allocated exclusively to instance network attachments or instance network interfaces.
Example:
500
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
The virtual server instance VCPU configuration
The volume attachments for this virtual server instance, including the boot volume attachment.
Possible values: number of items ≥ 1, contains only unique items
The VPC this virtual server instance resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual server instance resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, this virtual server instance was provisioned from a catalog.
The catalog offering version this virtual server instance was provisioned from.
The catalog offering version is not managed by the IBM VPC service, and may no longer exist, or may refer to a different image CRN than the
image.crn
for this virtual server instance. However, all images associated with a catalog offering version will have the same checksum, and therefore will have the same data.The CRN for this version of a catalog offering
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:globalcatalog-collection:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1082e7d2-5e2f-0a11-a3bc-f88a8e1931fc:version:00111601-0ec5-41ac-b142-96d1e64e6442/ec66bec2-6a33-42d6-9323-26dd4dc8875d
version
catalog_offering
If present, the dedicated host this virtual server instance has been placed on.
Examples:ViewThe CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
dedicated_host
The virtual server instance GPU configuration
The image the virtual server instance was provisioned from
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
image
The number of NUMA nodes this virtual server instance is provisioned on.
This property will be absent if the instance's
status
is notrunning
.Possible values: value ≥ 1
Example:
2
The placement restrictions for the virtual server instance
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
placement_target
The primary network attachment for this virtual server instance
Examples:ViewThe URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
The reservation used by this virtual server instance.
If absent, no reservation is in use.
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
reservation
Status Code
The instance was created successfully.
An invalid instance prototype object was provided.
The provided instance prototype object specified one or more of:
- An image that is not provisionable
- A placement target that does not support the instance profile
- A placement target or reservation attachment policy that conflict with each other
- A volume for the boot volume attachment that is not
unattached
{ "availability_policy": { "host_failure": "restart" }, "bandwidth": 4000, "boot_volume_attachment": { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, "confidential_compute_mode": "sgx", "created_at": "2020-03-26T16:11:57Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "dedicated_host": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "disks": [], "enable_secure_boot": true, "health_reasons": [], "health_state": "ok", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "image": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "name": "my-image", "resource_type": "image" }, "lifecycle_reasons": [], "lifecycle_state": "pending", "memory": 8, "metadata_service": { "enabled": true, "protocol": "http", "response_hop_limit": 1 }, "name": "my-instance", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "numa_count": 2, "placement_target": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16", "name": "bx2-4x16", "resource_type": "instance_profile" }, "reservation_affinity": { "policy": "disabled", "pool": [] }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "instance", "startable": true, "status": "pending", "status_reasons": [], "total_network_bandwidth": 3000, "total_volume_bandwidth": 1000, "vcpu": { "architecture": "amd64", "count": 2, "manufacturer": "intel" }, "volume_attachments": [ { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, { "device": { "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "name": "my-volume-attachment-2", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "name": "my-volume-2", "resource_type": "volume" } } ], "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete an instance
This request deletes an instance. This operation cannot be reversed. Any floating IPs
associated with instance network interfaces are implicitly disassociated. All virtual
network interfaces with auto_delete
set to true
targeting instance network
attachments on the instance are automatically deleted. All flow log collectors with
auto_delete
set to true
targeting the instance, the instance network attachments,
the instance network interfaces, or the automatically deleted virtual network interfaces
are automatically deleted.
DELETE /instances/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.instance.delete
is.instance.network-attachment.delete
Generated for each network attachment on the instance
is.instance.network-attachment.detach
Generated for each network attachment on the instance
is.instance.network-interface.delete
Generated for each network interface on the instance
is.instance.network-interface.detach
Generated for each resource attached to a network interface on the instance:
- reserved IPs
- security groups
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to:
- a network interface on the instance, or
- a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to:- a network interface on the instance, or
- a virtual network interface that had
auto_delete
set totrue
is.security-group.security-group.detach
Generated for each security group that was attached to:
- a network interface on the instance, or
- a virtual network interface that had
auto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
is.virtual-network-interface.virtual-network-interface.detach
Generated for:
- each attached virtual network interface
- each virtual network interface that had
auto_delete
set totrue
, for each attached reserved IP
is.virtual-network-interface.virtual-network-interface.delete
Generated for each virtual network interface that had
auto_delete
set totrue
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to:
- a network interface on the instance, or
- a virtual network interface that had
auto_delete
set totrue
is.flow-log-collector.flow-log-collector.delete
Generated for each flow log collector that had
auto_delete
set totrue
that was attached to:- the instance
- a network interface on the instance
- a network attachment on the instance
- a virtual network interface that had
auto_delete
set totrue
is.flow-log-collector.flow-log-collector.detach
Generated for each flow log collector that was attached to:
- the instance
- a network interface on the instance
- a network attachment on the instance
- a virtual network interface that had
auto_delete
set totrue
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceOptions{} options.SetID(id) response, err := vpcService.DeleteInstance(options)
DeleteInstanceOptions deleteInstanceOptions = new DeleteInstanceOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteInstance(deleteInstanceOptions).execute();
const response = await vpcService.deleteInstance({ id });
response = service.delete_instance(id)
Retrieve an instance
This request retrieves a single instance specified by the identifier in the URL.
GET /instances/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceOptions{} options.SetID(instanceID) instance, response, err := vpcService.GetInstance(options)
GetInstanceOptions getInstanceOptions = new GetInstanceOptions.Builder() .id(id) .build(); Response<Instance> response = service.getInstance(getInstanceOptions).execute(); Instance instance = response.getResult();
const response = await vpcService.getInstance({ id });
response = service.get_instance(id)
Response
The availability policy for this virtual server instance
The action to perform if the compute host experiences a failure:
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
The enumerated values for this property may expand in the future.
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The total bandwidth (in megabits per second) shared across the instance network attachments or instance network interfaces and storage volumes of the virtual server instance
Example:
1000
Boot volume attachment
Examples:ViewThe URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
boot_volume_attachment
The confidential compute mode for this virtual server instance.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the virtual server instance was created
The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The instance disks for this virtual server instance.
Possible values: number of items ≥ 0
Indicates whether secure boot is enabled for this virtual server instance.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the virtual server instance.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 512
Example:
8
The metadata service configuration
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
The network attachments for this virtual server instance, including the primary network attachment.
Possible values: number of items ≥ 0, contains only unique items
The network interfaces for this instance, including the primary network interface.
If this instance has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
Possible values: number of items ≥ 1, contains only unique items
The primary network interface for this virtual server instance.
If this instance has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.
Examples:ViewThe URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this virtual server instance
Examples:ViewThe URL for this virtual server instance profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
The resource type
Possible values: [
instance_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this instance
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether the state of the virtual server instance permits a start request.
The status of the virtual server instance.
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,pending
,restarting
,running
,starting
,stopped
,stopping
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The amount of bandwidth (in megabits per second) allocated exclusively to instance network attachments or instance network interfaces.
Example:
500
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
The virtual server instance VCPU configuration
The volume attachments for this virtual server instance, including the boot volume attachment.
Possible values: number of items ≥ 1, contains only unique items
The VPC this virtual server instance resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual server instance resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, this virtual server instance was provisioned from a catalog.
The catalog offering version this virtual server instance was provisioned from.
The catalog offering version is not managed by the IBM VPC service, and may no longer exist, or may refer to a different image CRN than the
image.crn
for this virtual server instance. However, all images associated with a catalog offering version will have the same checksum, and therefore will have the same data.The CRN for this version of a catalog offering
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:globalcatalog-collection:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1082e7d2-5e2f-0a11-a3bc-f88a8e1931fc:version:00111601-0ec5-41ac-b142-96d1e64e6442/ec66bec2-6a33-42d6-9323-26dd4dc8875d
version
catalog_offering
If present, the dedicated host this virtual server instance has been placed on.
Examples:ViewThe CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
dedicated_host
The virtual server instance GPU configuration
The image the virtual server instance was provisioned from
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
image
The number of NUMA nodes this virtual server instance is provisioned on.
This property will be absent if the instance's
status
is notrunning
.Possible values: value ≥ 1
Example:
2
The placement restrictions for the virtual server instance
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
placement_target
The primary network attachment for this virtual server instance
Examples:ViewThe URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
The reservation used by this virtual server instance.
If absent, no reservation is in use.
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
reservation
Status Code
The instance was retrieved successfully.
An instance with the specified identifier could not be found.
{ "availability_policy": { "host_failure": "restart" }, "bandwidth": 4000, "boot_volume_attachment": { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, "confidential_compute_mode": "sgx", "created_at": "2020-03-26T16:11:57Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "dedicated_host": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "disks": [], "enable_secure_boot": true, "health_reasons": [], "health_state": "ok", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "image": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "name": "my-image", "resource_type": "image" }, "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 8, "metadata_service": { "enabled": true, "protocol": "http", "response_hop_limit": 1 }, "name": "my-instance", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "numa_count": 2, "placement_target": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16", "name": "bx2-4x16", "resource_type": "instance_profile" }, "reservation_affinity": { "policy": "disabled", "pool": [] }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "instance", "startable": true, "status": "running", "status_reasons": [], "total_network_bandwidth": 3000, "total_volume_bandwidth": 1000, "vcpu": { "architecture": "amd64", "count": 2, "manufacturer": "intel" }, "volume_attachments": [ { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, { "device": { "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "name": "my-volume-attachment-2", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "name": "my-volume-2", "resource_type": "volume" } } ], "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update an instance
This request updates an instance with the information in a provided instance patch. The instance patch object is structured in the same way as a retrieved instance and contains only the information to be updated.
PATCH /instances/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.instance.update
is.instance.instance.detach
Generated for each reservation being removed from
reservation_affinity.pool
.is.reservation.reservation.detach
Generated for each reservation being removed from
reservation_affinity.pool
.is.instance.instance.attach
Generated for each reservation being added to
reservation_affinity.pool
.is.reservation.reservation.attach
Generated for each reservation being added to
reservation_affinity.pool
.
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance patch
The availability policy for this virtual server instance
The action to perform if the compute host experiences a failure.
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
Allowable values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The confidential compute mode to use for this virtual server instance. To change this property to
sgx
,reservation_affinity.policy
must be set todisabled
.For this property to be changed, the virtual server instance
status
must bestopping
orstopped
.Allowable values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether secure boot is enabled for this virtual server instance.
For this property to be changed, the virtual server instance
status
must bestopping
orstopped
.The metadata service configuration
The name for this virtual server instance. The name must not be used by another virtual server instance in the region. Changing the name will not affect the system hostname.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance
The placement restrictions to use for the virtual server instance. For the placement restrictions to be changed, the instance
status
must bestopping
orstopped
.If set,
reservation_affinity.policy
must bedisabled
.placement_target
The profile to use for this virtual server instance. For the profile to be changed, the instance
status
must bestopping
orstopped
. In addition, the requested profile must:- Have matching instance disk support. Any disks associated with the current profile will be deleted, and any disks associated with the requested profile will be created.
- Be compatible with any
placement_target
constraints. For example, if the instance is placed on a dedicated host, the requested profilefamily
must be the same as the dedicated hostfamily
. - Have the same
vcpu.architecture
. - Support the number of network attachments or network interfaces the instance currently has.
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
profile
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{"name": "my-instance"}'
options := &vpcv1.UpdateInstanceOptions{} options.SetID(id) options.SetName(name) instance, response, err := vpcService.UpdateInstance(options)
UpdateInstanceOptions updateInstanceOptions = new UpdateInstanceOptions.Builder() .id(id) .name(name) .build(); Response<Instance> response = service.updateInstance(updateInstanceOptions).execute(); Instance instance = response.getResult();
const response = await vpcService.updateInstance({ id, name: 'my-instance', });
response = service.update_instance( id, name='my-instance', )
Response
The availability policy for this virtual server instance
The action to perform if the compute host experiences a failure:
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
The enumerated values for this property may expand in the future.
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
availability_policy
The total bandwidth (in megabits per second) shared across the instance network attachments or instance network interfaces and storage volumes of the virtual server instance
Example:
1000
Boot volume attachment
Examples:ViewThe URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
boot_volume_attachment
The confidential compute mode for this virtual server instance.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the virtual server instance was created
The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The instance disks for this virtual server instance.
Possible values: number of items ≥ 0
Indicates whether secure boot is enabled for this virtual server instance.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the virtual server instance.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 512
Example:
8
The metadata service configuration
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
The network attachments for this virtual server instance, including the primary network attachment.
Possible values: number of items ≥ 0, contains only unique items
The network interfaces for this instance, including the primary network interface.
If this instance has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
Possible values: number of items ≥ 1, contains only unique items
The primary network interface for this virtual server instance.
If this instance has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.
Examples:ViewThe URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this virtual server instance
Examples:ViewThe URL for this virtual server instance profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
The resource type
Possible values: [
instance_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this instance
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether the state of the virtual server instance permits a start request.
The status of the virtual server instance.
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,pending
,restarting
,running
,starting
,stopped
,stopping
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The amount of bandwidth (in megabits per second) allocated exclusively to instance network attachments or instance network interfaces.
Example:
500
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
The virtual server instance VCPU configuration
The volume attachments for this virtual server instance, including the boot volume attachment.
Possible values: number of items ≥ 1, contains only unique items
The VPC this virtual server instance resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual server instance resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
If present, this virtual server instance was provisioned from a catalog.
The catalog offering version this virtual server instance was provisioned from.
The catalog offering version is not managed by the IBM VPC service, and may no longer exist, or may refer to a different image CRN than the
image.crn
for this virtual server instance. However, all images associated with a catalog offering version will have the same checksum, and therefore will have the same data.The CRN for this version of a catalog offering
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:globalcatalog-collection:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1082e7d2-5e2f-0a11-a3bc-f88a8e1931fc:version:00111601-0ec5-41ac-b142-96d1e64e6442/ec66bec2-6a33-42d6-9323-26dd4dc8875d
version
catalog_offering
If present, the dedicated host this virtual server instance has been placed on.
Examples:ViewThe CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
dedicated_host
The virtual server instance GPU configuration
The image the virtual server instance was provisioned from
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
image
The number of NUMA nodes this virtual server instance is provisioned on.
This property will be absent if the instance's
status
is notrunning
.Possible values: value ≥ 1
Example:
2
The placement restrictions for the virtual server instance
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
placement_target
The primary network attachment for this virtual server instance
Examples:ViewThe URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
The reservation used by this virtual server instance.
If absent, no reservation is in use.
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
reservation
Status Code
The instance was updated successfully.
An invalid instance patch was provided.
The instance is not allowed to be updated.
An instance with the specified identifier could not be found.
The provided instance patch object specified one or more of:
- A property that can only be changed while the instance
status
isstopped
orstopping
- An instance profile does not support the instance configuration
- A placement target or reservation attachment policy that conflict with each other
- A property that can only be changed while the instance
The provided
If-Match
value does not match the current ETag value of the instance
{ "availability_policy": { "host_failure": "restart" }, "bandwidth": 4000, "boot_volume_attachment": { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, "confidential_compute_mode": "sgx", "created_at": "2020-03-26T16:11:57Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "dedicated_host": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "disks": [], "enable_secure_boot": true, "health_reasons": [], "health_state": "ok", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "image": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "name": "my-image", "resource_type": "image" }, "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 8, "metadata_service": { "enabled": true, "protocol": "http", "response_hop_limit": 1 }, "name": "my-instance-updated", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "numa_count": 2, "placement_target": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-network-attachment", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-instance-network-interface", "primary_ip": { "address": "10.240.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-4x16", "name": "bx2-4x16", "resource_type": "instance_profile" }, "reservation_affinity": { "policy": "disabled", "pool": [] }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345", "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "instance", "startable": true, "status": "running", "status_reasons": [], "total_network_bandwidth": 3000, "total_volume_bandwidth": 1000, "vcpu": { "architecture": "amd64", "count": 2, "manufacturer": "intel" }, "volume_attachments": [ { "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, { "device": { "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "name": "my-volume-attachment-2", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "name": "my-volume-2", "resource_type": "volume" } } ], "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Retrieve initialization configuration for an instance
This request retrieves configuration used to initialize the instance, such as SSH keys and the Windows administrator password. These can subsequently be changed on the instance and therefore may not be current.
GET /instances/{id}/initialization
Request
Path Parameters
The instance identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/initialization?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceInitializationOptions{} options.SetID(instanceID) initData, response, err := vpcService.GetInstanceInitialization(options)
GetInstanceInitializationOptions getInstanceInitializationOptions = new GetInstanceInitializationOptions.Builder() .id(id) .build(); Response<InstanceInitialization> response = service.getInstanceInitialization(getInstanceInitializationOptions).execute(); InstanceInitialization instanceInitialization = response.getResult();
const response = await vpcService.getInstanceInitialization({ id });
response = service.get_instance_initialization(id)
Response
The public SSH keys used at instance initialization.
The default trusted profile configuration specified at virtual server instance creation. If absent, no default trusted profile was specified.
If set to
true
, the system created a link to the specifiedtarget
trusted profile during instance creation. Regardless of whether a link was created by the system or manually using the IAM Identity service, it will be automatically deleted when the instance is deleted.Example:
true
The default IAM trusted profile to use for this virtual server instance
The CRN for this trusted profile
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
The resource type
Possible values: [
trusted_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
target
default_trusted_profile
Status Code
The initialization configuration was retrieved successfully.
An instance with the specified identifier could not be found.
{ "default_trusted_profile": { "auto_link": true, "target": { "crn": "crn:[...]", "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5", "resource_type": "trusted_profile" } }, "keys": [ { "crn": "crn:[...]", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/82679077-ac3b-4c10-be16-63e9c21f0f45", "id": "82679077-ac3b-4c10-be16-63e9c21f0f45", "name": "my-key-1" } ] }
Create an instance action
This request creates a new action which will be queued up to run as soon as any pending or running actions have completed.
POST /instances/{instance_id}/actions
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance action prototype object
The type of action
Allowable values: [
reboot
,start
,stop
]If set to true, the action will be forced immediately, and all queued actions deleted. Ignored for the start action.
curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/actions?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{"type": "stop"}'
options := &vpcv1.CreateInstanceActionOptions{} options.SetInstanceID(instanceID) options.SetType("stop") action, response, err := vpcService.CreateInstanceAction(options)
CreateInstanceActionOptions createInstanceActionOptions = new CreateInstanceActionOptions.Builder() .instanceId(instanceId) .type("reboot") .build(); Response<InstanceAction> response = service.createInstanceAction(createInstanceActionOptions).execute(); InstanceAction instanceAction = response.getResult();
const params = { instanceId, type: 'reboot', }; const response = await vpcService.createInstanceAction(params);
response = service.create_instance_action( instance_id, typ='reboot', )
Response
The date and time that the action was created
The URL for this instance action
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/actions/109a1b6e-1242-4de1-be44-38705e9474ed
The identifier for this instance action
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
109a1b6e-1242-4de1-be44-38705e9474ed
The current status of this action
Possible values: [
completed
,failed
,pending
,running
]The type of action
Possible values: [
reboot
,start
,stop
]The date and time that the action was completed
If set to true, the action will be forced immediately, and all queued actions deleted. Ignored for the start action.
The date and time that the action was started
Status Code
The action was created successfully and will run in the order it was received.
The specified action could not be created.
The action is not allowed to be created.
An instance with the specified identifier could not be found.
{ "completed_at": "2019-01-31T09:02:30.639Z", "created_at": "2019-01-31T09:02:18.653Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/abd870d3-c55f-0342-0899-c74082c16579/actions/d6c3902d-1ecf-3a2c-b7ab-eb9143581000", "id": "d6c3902d-1ecf-3a2c-b7ab-eb9143581000", "started_at": "2019-01-31T09:02:18.653Z", "status": "running", "type": "stop" }
Retrieve the console WebSocket for an instance
This retrieves a WebSocket providing a console for the instance. 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.
GET /instances/{instance_id}/console
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A URL safe single-use token used to access the console WebSocket.
Example:
VGhpcyBJcyBhIHRva2Vu
Create a console access token for an instance
This request creates a new single-use console access token for an instance.
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 instance at a time.
POST /instances/{instance_id}/console_access_token
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance console access token prototype
The instance console type for which this token may be used
Allowable values: [
serial
,vnc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
serial
Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.
Default:
false
curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/console_access_token?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "console_type": "serial", "force": true }'
createInstanceConsoleAccessTokenOptions := vpcService.NewCreateInstanceConsoleAccessTokenOptions( instanceID, console_type='serial', ) instanceConsoleAccessToken, response, err := vpcService.CreateInstanceConsoleAccessToken(createInstanceConsoleAccessTokenOptions)
CreateInstanceConsoleAccessTokenOptions createInstanceConsoleAccessTokenOptions = new CreateInstanceConsoleAccessTokenOptions.Builder() .instanceId(instanceId) .consoleType("serial") .build(); Response<InstanceConsoleAccessToken> response = service.createInstanceConsoleAccessToken(createInstanceConsoleAccessTokenOptions).execute();
const params = { instanceId, consoleType: 'serial', }; const response = await vpcService.createInstanceConsoleAccessToken(params);
instance_console_access_token = vpc_service.create_instance_console_access_token( instance_id, console_type='serial' )
Response
The instance console access token information
A URL safe single-use token used to access the console WebSocket.
Example:
VGhpcyBJcyBhIHRva2Vu
The instance console type for which this token may be used
Possible values: [
serial
,vnc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
serial
The date and time that the access token was created
Example:
2020-07-27T21:50:14.000Z
The date and time that the access token will expire
Example:
2020-07-27T21:51:14.000Z
Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.
The URL to access this instance console.
Example:
wss://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/console?access_token=VGhpcyBJcyBhIHRva2Vu
Status Code
The access token was created successfully.
An invalid instance console access token prototype object was provided.
The access token is not allowed to be created.
An instance with the specified identifier could not be found.
{ "access_token": "VGhpcyBJcyBhIHRva2Vu", "console_type": "serial", "created_at": "2021-02-01T07:09:45Z", "expires_at": "2021-02-01T07:09:45Z", "force": true, "href": "wss://us-south.iaas.cloud.ibm.com/v1/instances/0717-eb1b7391-2ca2-4ab5-84a8-b92157a633b0/console?access_token=VGhpcyBJcyBhIHRva2Vu&version=2024-04-30&generation=2&maturity=beta" }
List all disks on an instance
This request lists all disks on an instance. A disk is a block device that is
locally attached to the instance's physical host and is also referred to as instance
storage. By default, the listed disks are sorted by their created_at
property
values, with the newest disk first.
GET /instances/{instance_id}/disks
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/disks?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listInstanceDisksOptions := vpcService.NewListInstanceDisksOptions( instanceID, ) instanceDisksCollection, response, err := vpcService.ListInstanceDisks(listInstanceDisksOptions)
ListInstanceDisksOptions listInstanceDisksOptions = new ListInstanceDisksOptions.Builder() .instanceId(instanceId) .build(); Response<InstanceDiskCollection> response = service.listInstanceDisks(listInstanceDisksOptions).execute();
const response = await vpcService.listInstanceDisks({instanceId})
instance_disk_collection = vpc_service.list_instance_disks( instance_id, )
Retrieve an instance disk
This request retrieves a single instance disk specified by the identifier in the URL.
GET /instances/{instance_id}/disks/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getInstanceDiskOptions := vpcService.NewGetInstanceDiskOptions( instanceID, diskID, ) instanceDisk, response, err := vpcService.GetInstanceDisk(getInstanceDiskOptions)
GetInstanceDiskOptions getInstanceDiskOptions = new GetInstanceDiskOptions.Builder() .instanceId(instanceId) .id(diskId) .build(); Response<InstanceDisk> response = service.getInstanceDisk(getInstanceDiskOptions).execute();
const response = await vpcService.getInstanceDisk({instanceId, id})
instance_disk = vpc_service.get_instance_disk( instance_id, id )
Response
The date and time that the disk was created
The URL for this instance disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The disk interface used for attaching the disk.
The enumerated values for this property may expand in the future.
Possible values: [
nvme
,virtio_blk
]The name for this instance disk. The name is unique across all disks on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-disk
The resource type
Possible values: [
instance_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
Possible values: 1 ≤ value ≤ 100000
Example:
100
Status Code
The instance disk was retrieved successfully.
An instance disk with the specified identifier could not be found.
No Sample Response
Update an instance disk
This request updates the instance disk with the information in a provided patch.
PATCH /instances/{instance_id}/disks/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance disk patch
The name for this instance disk. The name must not be used by another disk on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-disk-updated
curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-disk-updated" }'
instanceDiskPatchModel := &vpcv1.InstanceDiskPatch{ Name: &name, } instanceDiskPatchModelAsPatch, asPatchErr := instanceDiskPatchModel.AsPatch() updateInstanceDiskOptions := vpcService.NewUpdateInstanceDiskOptions( instanceID, diskID, instanceDiskPatchModelAsPatch, )
InstanceDiskPatch instanceDiskPatchModel = new InstanceDiskPatch.Builder() .name("my-disk-update") .build(); Map<String, Object> instanceDiskPatchModelAsPatch = instanceDiskPatchModel.asPatch(); UpdateInstanceDiskOptions updateInstanceDiskOptions = new UpdateInstanceDiskOptions.Builder() .instanceId(instanceId) .id(diskId) .instanceDiskPatch(instanceDiskPatchModelAsPatch) .build();
const response = await vpcService.updateInstanceDisk({ instanceId, id, name, })
instance_disk_patch_model = { name='my-disk-updated' } instance_disk = vpc_service.update_instance_disk( instance_id, id, instance_disk_patch=instance_disk_patch_model )
Response
The date and time that the disk was created
The URL for this instance disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The disk interface used for attaching the disk.
The enumerated values for this property may expand in the future.
Possible values: [
nvme
,virtio_blk
]The name for this instance disk. The name is unique across all disks on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-disk
The resource type
Possible values: [
instance_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
Possible values: 1 ≤ value ≤ 100000
Example:
100
Status Code
The instance disk was updated successfully.
An invalid instance disk patch was provided.
The instance disk is not allowed to be updated.
An instance disk with the specified identifier could not be found for the specified instance.
No Sample Response
List all network attachments on an instance
This request lists all network attachments on an instance. A network attachment represents a device on the instance to which a virtual network interface is attached.
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.
GET /instances/{instance_id}/network_attachments
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceNetworkAttachmentsOptions{} options.SetInstanceID(id) networkAttachmentsCollection, response, err := vpcService.ListInstanceNetworkAttachments( options)
ListInstanceNetworkAttachmentsOptions listInstanceNetworkAttachmentsOptions = new ListInstanceNetworkAttachmentsOptions.Builder() .instanceId(instanceId) .build(); Response<InstanceNetworkAttachmentCollection> response = vpcService.listInstanceNetworkAttachments(listInstanceNetworkAttachmentsOptions).execute(); InstanceNetworkAttachmentCollection instanceNetworkAttachmentCollection = response.getResult();
const response = await vpcService.listInstanceNetworkAttachments({ instanceId });
response = vpc_service.list_instance_network_attachments( instance_id=instance_id, ) instance_network_attachment_collection = response.get_result()
Response
Collection of instance network attachments
Status Code
The instance network attachments were retrieved successfully.
An instance with the specified identifier could not be found.
{ "network_attachments": [ { "created_at": "2019-01-31T03:42:32.993Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_attachments/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/5e2c7f65-6393-4345-a5b7-3d13242ae68d", "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } } ] }
Create a network attachment on an instance
This request creates a new instance network attachment from an instance network attachment prototype object. The prototype object is structured in the same way as a retrieved instance network attachment, and contains the information necessary to create the new instance network attachment.
POST /instances/{instance_id}/network_attachments
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.create
Generated for each virtual network interface created
is.virtual-network-interface.virtual-network-interface.attach
Generated for:
- each virtual network interface being attached to an instance network attachment
- each virtual network interface for each reserved IP being attached to it
- each virtual network interface for each security group being attached to it
is.instance.network-attachment.attach
Generated for each virtual network interface being attached to an instance network attachment
is.instance.network-attachment.create
is.security-group.security-group.attach
Generated for each security group being attached to a new virtual network interface
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.subnet.subnet.update
Generated for each reserved IP created
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to a virtual network interface
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance network attachment prototype object
A virtual network interface for the instance 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,
enable_infrastructure_nat
must betrue
.The name for this network attachment. Names must be unique within the instance the network attachment resides in. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-network-attachment", "virtual_network_interface": { "id": "0767-fa41aecb-4f21-423d-8082-630bfba1e1d9" } }'
options := &vpcv1.CreateInstanceNetworkAttachmentOptions{} options.SetInstanceID(instanceId) options.SetName("instance-network-attachment") options.SetVirtualNetworkInterface(&vpcv1.InstanceNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfaceIdentity{ ID: &virtualNetworkInterfaceId, }) networkAttachment, response, err := vpcService.CreateInstanceNetworkAttachment( options)
VirtualNetworkInterfacePrimaryIPPrototypeReservedIPPrototypeVirtualNetworkInterfacePrimaryIPContext virtualNetworkInterfacePrimaryIpPrototypeModel = new VirtualNetworkInterfacePrimaryIPPrototypeReservedIPPrototypeVirtualNetworkInterfacePrimaryIPContext.Builder() .address("10.0.0.7") .autoDelete(false) .build(); InstanceNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfacePrototypeInstanceNetworkAttachmentContext instanceNetworkAttachmentPrototypeVirtualNetworkInterfaceModel = new InstanceNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfacePrototypeInstanceNetworkAttachmentContext.Builder() .primaryIp(virtualNetworkInterfacePrimaryIpPrototypeModel) .build(); CreateInstanceNetworkAttachmentOptions createInstanceNetworkAttachmentOptions = new CreateInstanceNetworkAttachmentOptions.Builder() .instanceId("testString") .name("my-instance-network-attachment") .virtualNetworkInterface(instanceNetworkAttachmentPrototypeVirtualNetworkInterfaceModel) .build(); Response<InstanceNetworkAttachment> response = vpcService.createInstanceNetworkAttachment(createInstanceNetworkAttachmentOptions).execute(); InstanceNetworkAttachment instanceNetworkAttachment = response.getResult();
const virtualNetworkInterfacePrimaryIpPrototypeModel = { address: '10.0.0.7', auto_delete: false, }; const instanceNetworkAttachmentPrototypeVirtualNetworkInterfaceModel = { primary_ip: virtualNetworkInterfacePrimaryIpPrototypeModel, }; const params = { instanceId: instanceId, name: 'my-instance-network-attachment', virtualNetworkInterface: instanceNetworkAttachmentPrototypeVirtualNetworkInterfaceModel, }; const response = await vpcService.createInstanceNetworkAttachment(params);
virtual_network_interface_primary_ip_prototype_model = { 'address': '10.0.0.7', } subnet_identity_model = {} subnet_identity_model['id'] = subnetId instance_network_attachment_prototype_virtual_network_interface_model = { 'primary_ip': virtual_network_interface_primary_ip_prototype_model, 'subnet': subnet_identity_model, } response = vpc_service.create_instance_network_attachment( instance_id=instance_id, name='my-instance-network-attachment', virtual_network_interface=instance_network_attachment_prototype_virtual_network_interface_model, ) instance_network_attachment = response.get_result()
Response
The date and time that the instance network attachment was created
The URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The lifecycle state of the instance network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The port speed for this instance network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this instance network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The instance network attachment was created successfully.
An invalid instance network attachment prototype object was provided.
An instance with the specified identifier could not be found.
{ "created_at": "2019-01-31T03:42:32.993Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_attachments/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/5e2c7f65-6393-4345-a5b7-3d13242ae68d", "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }
Delete an instance network attachment
This request deletes an instance network attachment. This operation cannot be reversed. Any
floating IPs associated with the instance network attachment are implicitly disassociated.
All flow log collectors with auto_delete
set to true
targeting the instance network
attachment are automatically deleted. The primary instance network attachment is not
allowed to be deleted.
DELETE /instances/{instance_id}/network_attachments/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.network-attachment.delete
is.instance.network-attachment.detach
Generated for each resource that was attached to this instance network attachment:
- a flow log collector
- a virtual network interface
is.virtual-network-interface.virtual-network-interface.detach
Generated for the attached virtual network interface, and also for each reserved IP that was attached to the virtual network interface if the virtual network interface had
auto_delete
set totrue
is.virtual-network-interface.virtual-network-interface.delete
Generated when the virtual network interface had
auto_delete
set totrue
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to an virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.security-group.security-group.detach
Generated for each security group that was attached to a virtual network interface that had
auto_delete
set totrue
is.flow-log-collector.flow-log-collector.delete
Generated for each flow log collector that had
auto_delete
set totrue
that was attached to:- this instance network attachment
- a virtual network interface that had
auto_delete
set totrue
is.flow-log-collector.flow-log-collector.detach
Generated for each flow log collector that was attached to:
- this instance network attachment
- a virtual network interface that had
auto_delete
set totrue
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceNetworkAttachmentOptions{} options.SetID(networkAttachmentID) options.SetInstanceID(instanceID) response, err := vpcService.DeleteInstanceNetworkAttachment(options)
DeleteInstanceNetworkAttachmentOptions deleteInstanceNetworkAttachmentOptions = new DeleteInstanceNetworkAttachmentOptions.Builder() .instanceId(instanceId) .id(instanceNetworkAttachmentId) .build(); Response<Void> response = vpcService.deleteInstanceNetworkAttachment(deleteInstanceNetworkAttachmentOptions).execute();
const response = await vpcService.deleteInstanceNetworkAttachment({ instanceId, instanceNetworkAttachmentId, });
response = vpc_service.delete_instance_network_attachment( instance_id=instance_id, id=instance_network_attachment_id, )
Retrieve an instance network attachment
This request retrieves a single instance network attachment specified by the identifier in the URL.
GET /instances/{instance_id}/network_attachments/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceNetworkAttachmentOptions{} options.SetID(networkAttachmentID) options.SetInstanceID(instanceID) networkAttachment, response, err := vpcService.GetInstanceNetworkAttachment(options)
GetInstanceNetworkAttachmentOptions getInstanceNetworkAttachmentOptions = new GetInstanceNetworkAttachmentOptions.Builder() .instanceId(instanceId) .id(instanceNetworkAttachmentId) .build(); Response<InstanceNetworkAttachment> response = vpcService.getInstanceNetworkAttachment(getInstanceNetworkAttachmentOptions).execute(); InstanceNetworkAttachment instanceNetworkAttachment = response.getResult();
const response = await vpcService.getInstanceNetworkAttachment({ instanceId, instanceNetworkAttachmentId, });
response = vpc_service.get_instance_network_attachment( instance_id=instance_id, id=instance_network_attachment_id, ) instance_network_attachment = response.get_result()
Response
The date and time that the instance network attachment was created
The URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The lifecycle state of the instance network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The port speed for this instance network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this instance network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The instance network attachment was retrieved successfully.
A instance network attachment with the specified identifier could not be found.
{ "created_at": "2019-01-31T03:42:32.993Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_attachments/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/5e2c7f65-6393-4345-a5b7-3d13242ae68d", "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }
Update an instance network attachment
This request updates an instance network attachment with the information provided in an instance network interface patch object. The instance network attachment patch object is structured in the same way as a retrieved instance network attachment and needs to contain only the information to be updated.
PATCH /instances/{instance_id}/network_attachments/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance network attachment patch
The name for this network attachment. The name must not be used by another network attachment for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment-updated
curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-network-attachment-updated" }'
options := &vpcv1.UpdateInstanceNetworkAttachmentOptions{} options.SetID(networkAttachmentID) options.SetInstanceID(instanceID) options.SetName(name) networkAttachment, response, err := vpcService.UpdateInstanceNetworkAttachment( options)
InstanceNetworkAttachmentPatch instanceNetworkAttachmentPatchModel = new InstanceNetworkAttachmentPatch.Builder() .name("my-instance-network-attachment-updated") .build(); Map<String, Object> instanceNetworkAttachmentPatchModelAsPatch = instanceNetworkAttachmentPatchModel.asPatch(); UpdateInstanceNetworkAttachmentOptions updateInstanceNetworkAttachmentOptions = new UpdateInstanceNetworkAttachmentOptions.Builder() .instanceId(instanceId) .id(instanceNetworkAttachmentId) .instanceNetworkAttachmentPatch(instanceNetworkAttachmentPatchModelAsPatch) .build(); Response<InstanceNetworkAttachment> response = vpcService.updateInstanceNetworkAttachment(updateInstanceNetworkAttachmentOptions).execute(); InstanceNetworkAttachment instanceNetworkAttachment = response.getResult();
const params = { instanceId: instanceId, id: instanceNetworkAttachmentId, name: 'my-instance-network-attachment-updated', }; const response = await vpcService.updateInstanceNetworkAttachment(params);
instance_network_attachment_patch_model = { 'name': 'my-instance-network-attachment-updated', } response = vpc_service.update_instance_network_attachment( instance_id=instance_id, id=instance_network_attachment_id, instance_network_attachment_patch=instance_network_attachment_patch_model, ) instance_network_attachment = response.get_result()
Response
The date and time that the instance network attachment was created
The URL for this instance network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/5dd61d72-acaa-47c2-a336-3d849660d010/network_attachments/0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The lifecycle state of the instance network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The port speed for this instance network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the instance network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this instance network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The instance network attachment was updated successfully.
An invalid instance network attachment patch was provided.
A instance network attachment with the specified identifier could not be found.
{ "created_at": "2019-01-31T03:42:32.993Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_attachments/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.0.5", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/5e2c7f65-6393-4345-a5b7-3d13242ae68d", "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }
List all network interfaces on an instance
This request lists all network interfaces on an instance. An instance network interface is an abstract representation of a network device and attaches an instance to a single subnet. Each network interface on an instance can attach to any subnet in the zone, including subnets that are already attached to the instance. Multiple network interfaces on the instance may also attach to the same subnet.
If this instance has network attachments, each returned network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
GET /instances/{instance_id}/network_interfaces
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceNetworkInterfacesOptions{} options.SetInstanceID(id) networkInterfaces, response, err := vpcService.ListInstanceNetworkInterfaces( options)
ListInstanceNetworkInterfacesOptions listInstanceNetworkInterfacesOptions = new ListInstanceNetworkInterfacesOptions.Builder() .instanceId(instanceId) .build(); Response<NetworkInterfaceUnpaginatedCollection> response = service.listInstanceNetworkInterfaces(listInstanceNetworkInterfacesOptions).execute(); NetworkInterfaceUnpaginatedCollection networkInterfaceUnpaginatedCollection = response.getResult();
const response = await vpcService.listInstanceNetworkInterfaces({ id });
response = service.list_instance_network_interfaces(instance_id)
Response
Collection of instance network interfaces
Status Code
The instance network interfaces were retrieved successfully.
An instance with the specified identifier could not be found.
{ "network_interfaces": [ { "allow_ip_spoofing": false, "created_at": "2019-01-31T03:42:32.993Z", "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "molecule-find-wild-name-dictionary-trench", "port_speed": 1000, "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "before-entrance-mountain-paralegal-photo-uninstall" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary" } ] }
Create a network interface on an instance
This request creates a new instance network interface from an instance network interface prototype object. The prototype object is structured in the same way as a retrieved instance network interface, and contains the information necessary to create the new instance network interface. Any subnet in the instance's VPC may be specified. Addresses on the instance network interface must be within the specified subnet's CIDR blocks.
If this instance 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.
POST /instances/{instance_id}/network_interfaces
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.network-interface.create
is.instance.network-interface.attach
Generated for each resource being attached to an instance network interface:
- security groups
- reserved IPs
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to an instance network interface
is.security-group.security-group.attach
Generated for each security group being attached to an instance network interface
is.subnet.subnet.update
Generated for each reserved IP created
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance network interface prototype object
The associated subnet
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
subnet
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance 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.
Default:
false
Example:
true
The name for the instance network interface. The name must not be used by another network interface on the virtual server instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-network-interface
The primary IP address to bind to the instance 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 instance network interface's subnet. Otherwise, an available address on the subnet will be automatically selected and reserved.
primary_ip
The security groups to use for this instance network interface. If unspecified, the VPC's default security group is used.
Possible values: contains only unique items
Examples:Viewsecurity_groups
curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-network-interface", "subnet": { "id": "8722d01c-9c78-4555-82b5-53ad1266f959" } }'
options := &vpcv1.CreateInstanceNetworkInterfaceOptions{} options.SetInstanceID(id) options.SetName("eth1") options.SetSubnet(&vpcv1.SubnetIdentityByID{ ID: &subnetId, }) networkInterface, response, err := vpcService.CreateInstanceNetworkInterface( options)
SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(id) .build(); CreateInstanceNetworkInterfaceOptions createInstanceNetworkInterfaceOptions = new CreateInstanceNetworkInterfaceOptions.Builder() .instanceId(instanceId) .subnet(subnetIdentityModel) .name("my-network-interface") .build(); Response<NetworkInterface> response = service.createInstanceNetworkInterface(createInstanceNetworkInterfaceOptions).execute(); NetworkInterface networkInterface = response.getResult();
const params = { instanceId, subnet: { id: subnetID }, }; const response = await vpcService.createInstanceNetworkInterface(params);
subnet_identity_model = {} subnet_identity_model['id'] = subnet_id security_group_identity_model = {} security_group_identity_model['id'] = security_group_id subnet = subnet_identity_model name = 'eth-1' primary_ipv4_address = '10.0.0.5' security_groups = [security_group_identity_model] response = service.create_instance_network_interface( instance_id, subnet, name=name, primary_ipv4_address=primary_ipv4_address, security_groups=security_groups, )
Response
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance 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.
Example:
true
The date and time that the instance network interface was created.
If this instance has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.
The floating IPs associated with this instance network interface.
If this instance 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.
The URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The instance network interface port speed in Mbps.
If this instance 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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this instance network interface.
If this instance 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.
Possible values: number of items ≥ 1, contains only unique items
The status of the instance network interface.
If this instance 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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network interface type.
If this instance 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.
Possible values: [
primary
,secondary
]Example:
primary
Status Code
The instance network interface was created successfully.
An invalid instance network interface prototype object was provided.
The instance network interface is not allowed to be created.
An instance with the specified identifier could not be found.
{ "allow_ip_spoofing": false, "created_at": "2019-01-31T03:42:32.993Z", "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-network-interface-2", "port_speed": 1000, "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "before-entrance-mountain-paralegal-photo-uninstall" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "type": "secondary" }
Delete an instance network interface
This request deletes an instance network interface. This operation cannot be reversed.
Any floating IPs associated with the instance network interface are implicitly
disassociated. All flow log collectors with auto_delete
set to true
targeting the
instance network interface are automatically deleted. The primary instance network
interface is not allowed to be deleted.
If this instance 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.
DELETE /instances/{instance_id}/network_interfaces/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.instance.network-interface.delete
is.instance.network-interface.detach
Generated for each resource that was attached to this instance network interface:
- a floating IP
- a flow log collector
- a reserved IP
- security groups
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to this instance network interface
is.security-group.security-group.detach
Generated for each security group that was attached to this instance network interface
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to this instance network interface
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to this instance network interfaceis.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to this instance network interfaceis.flow-log-collector.flow-log-collector.delete
Generated for each flow log collector that had
auto_delete
set totrue
that was attached to this instance network interfaceis.flow-log-collector.flow-log-collector.detach
Generated for each flow log collector that was attached to this instance network interface
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceNetworkInterfaceOptions{} options.SetID(networkInterfaceID) options.SetInstanceID(instanceID) response, err := vpcService.DeleteInstanceNetworkInterface(options)
DeleteInstanceNetworkInterfaceOptions deleteInstanceNetworkInterfaceOptions = new DeleteInstanceNetworkInterfaceOptions.Builder() .instanceId(instanceId) .id(id) .build(); Response<Void> response = service.deleteInstanceNetworkInterface(deleteInstanceNetworkInterfaceOptions).execute();
const response = await vpcService.deleteInstanceNetworkInterface({ instanceGroupId, id, });
response = service.delete_instance_network_interface(instance_id, id)
Retrieve an instance network interface
This request retrieves a single instance network interface specified by the identifier in the URL.
If this instance has network attachments, the retrieved network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
GET /instances/{instance_id}/network_interfaces/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceNetworkInterfaceOptions{} options.SetID(networkID) options.SetInstanceID(instanceID) networkInterface, response, err := vpcService.GetInstanceNetworkInterface(options)
GetInstanceNetworkInterfaceOptions getInstanceNetworkInterfaceOptions = new GetInstanceNetworkInterfaceOptions.Builder() .instanceId(instanceId) .id(id) .build(); Response<NetworkInterface> response = service.getInstanceNetworkInterface(getInstanceNetworkInterfaceOptions).execute(); NetworkInterface networkInterface = response.getResult();
const response = await vpcService.getInstanceNetworkInterface({ instanceId, id, });
response = service.get_instance_network_interface(instance_id, network_interface_id)
Response
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance 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.
Example:
true
The date and time that the instance network interface was created.
If this instance has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.
The floating IPs associated with this instance network interface.
If this instance 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.
The URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The instance network interface port speed in Mbps.
If this instance 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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this instance network interface.
If this instance 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.
Possible values: number of items ≥ 1, contains only unique items
The status of the instance network interface.
If this instance 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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network interface type.
If this instance 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.
Possible values: [
primary
,secondary
]Example:
primary
Status Code
The instance network interface was retrieved successfully.
An instance network interface with the specified identifier could not be found.
{ "allow_ip_spoofing": false, "created_at": "2019-01-31T03:42:32.993Z", "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "molecule-find-wild-name-dictionary-trench", "port_speed": 1000, "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "before-entrance-mountain-paralegal-photo-uninstall" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary" }
Update an instance network interface
This request updates an instance network interface with the information provided in an instance network interface patch object. The instance network interface patch object is structured in the same way as a retrieved instance network interface and needs to contain only the information to be updated.
If this instance 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.
PATCH /instances/{instance_id}/network_interfaces/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance network interface patch
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance 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.
Example:
true
The name for the instance network interface. The name must not be used by another network interface on the virtual server instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-network-interface
curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "allow_ip_spoofing": true }'
options := &vpcv1.UpdateInstanceNetworkInterfaceOptions{} options.SetID(networkID) options.SetInstanceID(instanceID) options.SetName(name) networkInterface, response, err := vpcService.UpdateInstanceNetworkInterface( options)
UpdateInstanceNetworkInterfaceOptions updateInstanceNetworkInterfaceOptions = new UpdateInstanceNetworkInterfaceOptions.Builder() .instanceId(instanceId) .id(id) .name(name) .build(); Response<NetworkInterface> response = service.updateInstanceNetworkInterface(updateInstanceNetworkInterfaceOptions).execute(); NetworkInterface networkInterface = response.getResult();
const response = await vpcService.updateInstanceNetworkInterface({ instanceId, id, name: 'my-network-interface', });
response = service.update_instance_network_interface( instance_id, network_interface_id, name='eth2', )
Response
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance 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.
Example:
true
The date and time that the instance network interface was created.
If this instance has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.
The floating IPs associated with this instance network interface.
If this instance 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.
The URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The instance network interface port speed in Mbps.
If this instance 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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this instance network interface.
If this instance 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.
Possible values: number of items ≥ 1, contains only unique items
The status of the instance network interface.
If this instance 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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The instance network interface type.
If this instance 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.
Possible values: [
primary
,secondary
]Example:
primary
Status Code
The instance network interface was updated successfully.
An invalid instance network interface patch was provided.
The instance network interface is not allowed to be updated.
An instance network interface with the specified identifier could not be found.
{ "allow_ip_spoofing": false, "created_at": "2019-01-31T03:42:32.993Z", "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/123a490a-9e64-4254-a93b-9a3af3ede270/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-network-interface-1", "port_speed": 1000, "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "before-entrance-mountain-paralegal-photo-uninstall" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary" }
List all floating IPs associated with an instance network interface
This request lists all floating IPs associated with an instance network interface.
GET /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/floating_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceNetworkInterfaceFloatingIpsOptions{} options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) floatingIPs, response, err := vpcService.ListInstanceNetworkInterfaceFloatingIps(options)
ListInstanceNetworkInterfaceFloatingIpsOptions listInstanceNetworkInterfaceFloatingIpsOptions = new ListInstanceNetworkInterfaceFloatingIpsOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .build(); Response<FloatingIPUnpaginatedCollection> response = service.listInstanceNetworkInterfaceFloatingIps(listInstanceNetworkInterfaceFloatingIpsOptions).execute(); FloatingIPUnpaginatedCollection floatingIpUnpaginatedCollection = response.getResult();
const response = await vpcService.listInstanceNetworkInterfaceFloatingIps({ instanceId, networkInterfaceId, });
response = service.list_instance_network_interface_floating_ips( instance_id, network_interface_id)
Response
Collection of floating IPs
Status Code
The associated floating IPs were retrieved successfully.
An instance network interface with the specified identifier could not be found.
{ "floating_ips": [ { "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "pending", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32/network_interfaces/5a07e83d-c1f3-4df2-bcec-41b09c006847", "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847", "name": "my-network-interface-1", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ] }
Disassociate a floating IP from an instance network interface
This request disassociates the specified floating IP from the specified instance network interface
DELETE /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.RemoveInstanceNetworkInterfaceFloatingIPOptions{} options.SetID(floatingIpId) options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) response, err := vpcService.RemoveInstanceNetworkInterfaceFloatingIP(options)
RemoveInstanceNetworkInterfaceFloatingIpOptions removeInstanceNetworkInterfaceFloatingIpOptions = new RemoveInstanceNetworkInterfaceFloatingIpOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .id(id) .build(); Response<Void> response = service.removeInstanceNetworkInterfaceFloatingIp(removeInstanceNetworkInterfaceFloatingIpOptions).execute();
const response = await vpcService.removeInstanceNetworkInterfaceFloatingIp({ instanceId, networkInterfaceId, id, });
response = service.remove_instance_network_interface_floating_ip( instance_id, network_interface_id, id)
Retrieve associated floating IP
This request retrieves a specified floating IP address if it is associated with the instance network interface and instance specified in the URL
GET /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceNetworkInterfaceFloatingIPOptions{} options.SetID(floatingIpId) options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) floatingIP, response, err := vpcService.GetInstanceNetworkInterfaceFloatingIP(options)
GetInstanceNetworkInterfaceFloatingIpOptions getInstanceNetworkInterfaceFloatingIpOptions = new GetInstanceNetworkInterfaceFloatingIpOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .id(id) .build(); Response<FloatingIP> response = service.getInstanceNetworkInterfaceFloatingIp(getInstanceNetworkInterfaceFloatingIpOptions).execute(); FloatingIP floatingIp = response.getResult();
const response = await vpcService.getInstanceNetworkInterfaceFloatingIp({ instanceId, networkInterfaceId, id, });
response = service.get_instance_network_interface_floating_ip( instance_id, network_interface_id, id)
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The associated floating IP was retrieved successfully.
The floating IP address is not associated with an instance network interface with the specified identifier
{ "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "pending", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32/network_interfaces/5a07e83d-c1f3-4df2-bcec-41b09c006847", "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847", "name": "my-network-interface-1", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Associate a floating IP with an instance network interface
This request associates the specified floating IP with the specified instance network interface, replacing any existing association.
The existing floating IP must:
- not be required by another resource, such as a public gateway
- be in the same
zone
as the instance
A request body is not required, and if provided, is ignored.
PUT /instances/{instance_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.AddInstanceNetworkInterfaceFloatingIPOptions{} options.SetID(floatingIpId) options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) floatingIP, response, err := vpcService.AddInstanceNetworkInterfaceFloatingIP(options)
AddInstanceNetworkInterfaceFloatingIpOptions addInstanceNetworkInterfaceFloatingIpOptions = new AddInstanceNetworkInterfaceFloatingIpOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .id(id) .build(); Response<FloatingIP> response = service.addInstanceNetworkInterfaceFloatingIp(addInstanceNetworkInterfaceFloatingIpOptions).execute(); FloatingIP floatingIp = response.getResult();
const response = await vpcService.addInstanceNetworkInterfaceFloatingIp({ instanceId, networkInterfaceId, id, });
response = service.add_instance_network_interface_floating_ip( instance_id, network_interface_id, id)
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The floating IP was successfully associated with the instance network interface.
The specified floating IP could not be associated with the specified instance network interface.
The floating IP is not allowed to be associated.
The specified instance network interface or floating IP could not be found.
{ "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "pending", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32/network_interfaces/5a07e83d-c1f3-4df2-bcec-41b09c006847", "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847", "name": "my-network-interface-1", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List the primary reserved IP for an instance network interface
This request lists the primary reserved IP for an instance network interface.
GET /instances/{instance_id}/network_interfaces/{network_interface_id}/ips
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/reserved_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceNetworkInterfaceIpsOptions{} options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) reservedIPs, response, err := vpcService.ListInstanceNetworkInterfaceIps(options)
ListInstanceNetworkInterfaceIpsOptions listInstanceNetworkInterfaceIpsOptions = new ListInstanceNetworkInterfaceIpsOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .build(); Response<ReservedIPUnpaginatedCollection> response = service.listInstanceNetworkInterfaceIps(listInstanceNetworkInterfaceIpsOptions).execute(); ReservedIPUnpaginatedCollection ReservedIpUnpaginatedCollection = response.getResult();
const response = await vpcService.listInstanceNetworkInterfaceIps({ instanceId, networkInterfaceId, });
response = service.list_instance_network_interface_ips( instance_id, network_interface_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?limit=20
first
Collection of reserved IPs bound to an instance network interface
Possible values: number of items ≤ 1
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?start=a404e343444b4e1095c9edba76672d67&limit=20
next
Status Code
The reserved IPs were retrieved successfully.
An instance network interface with the specified identifier could not be found for the specified instance.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20/ips?limit=50" }, "ips": [ { "address": "10.240.0.7", "auto_delete": false, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-network-interface", "resource_type": "network_interface" } } ], "limit": 50, "total_count": 1 }
Retrieve the primary reserved IP
This request retrieves the primary reserved IP for an instance network interface.
GET /instances/{instance_id}/network_interfaces/{network_interface_id}/ips/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The instance network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id/reserved_ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceNetworkInterfaceIPOptions{} options.SetID(reservedIpId) options.SetInstanceID(instanceID) options.SetNetworkInterfaceID(networkID) reservedIP, response, err := vpcService.GetInstanceNetworkInterfaceIP(options)
GetInstanceNetworkInterfaceIpOptions getInstanceNetworkInterfaceIpOptions = new GetInstanceNetworkInterfaceIpOptions.Builder() .instanceId(instanceId) .networkInterfaceId(networkInterfaceId) .id(id) .build(); Response<ReservedIP> response = service.getInstanceNetworkInterfaceIp(getInstanceNetworkInterfaceIpOptions).execute(); ReservedIP ReservedIp = response.getResult();
const response = await vpcService.getInstanceNetworkInterfaceIp({ instanceId, networkInterfaceId, id, });
response = service.get_instance_network_interface_ip( instance_id, network_interface_id, id)
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The bound reserved IP was retrieved successfully.
The reserved IP address with the specified identifier could not be found
{ "address": "10.240.0.7", "auto_delete": false, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-network-interface", "resource_type": "network_interface" } }
List all volumes attachments on an instance
This request lists all volume attachments on an instance. A volume attachment connects a volume to an instance. Each instance may have many volume attachments but each volume attachment connects exactly one instance to exactly one volume.
GET /instances/{instance_id}/volume_attachments
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceVolumeAttachmentsOptions{} options.SetInstanceID(id) volumeAttachments, response, err := vpcService.ListInstanceVolumeAttachments( options)
ListInstanceVolumeAttachmentsOptions listInstanceVolumeAttachmentsOptions = new ListInstanceVolumeAttachmentsOptions.Builder() .instanceId(instanceId) .build(); Response<VolumeAttachmentCollection> response = service.listInstanceVolumeAttachments(listInstanceVolumeAttachmentsOptions).execute(); VolumeAttachmentCollection volumeAttachmentCollection = response.getResult();
const response = await vpcService.listInstanceVolumeAttachments({ instanceId });
response = service.list_instance_volume_attachments(instance_id)
Response
Collection of volume attachments
Status Code
The volume attachments were retrieved successfully.
An instance with the specified identifier could not be found.
{ "volume_attachments": [ { "bandwidth": 250, "created_at": "2019-02-28T16:32:05.000Z", "delete_volume_on_instance_delete": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/fdb3642d-c849-4c29-97a9-03b868616f88", "id": "fdb3642d-c849-4c29-97a9-03b868616f88", "name": "my-boot-volume-attachment", "status": "attached", "type": "boot", "volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ac0b16a5-ccc2-47dd-90e2-b9e5f367b6c6", "id": "ac0b16a5-ccc2-47dd-90e2-b9e5f367b6c6", "name": "my-boot-volume", "resource_type": "volume" } }, { "bandwidth": 250, "created_at": "2019-03-15T11:44:07.000Z", "delete_volume_on_instance_delete": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/8479a541-58ee-42ca-9efa-15a1551d42b9", "id": "8479a541-58ee-42ca-9efa-15a1551d42b9", "name": "my-data-volume-attachment", "status": "attached", "type": "data", "volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ca4b6df3-f5a8-4667-b5f2-f3b9b4160781", "id": "ca4b6df3-f5a8-4667-b5f2-f3b9b4160781", "name": "my-data-volume", "resource_type": "volume" } } ] }
Create a volume attachment on an instance
This request creates a new volume attachment from a volume attachment prototype object, connecting a volume to an instance. 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.
POST /instances/{instance_id}/volume_attachments
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The volume attachment prototype object
An existing volume to attach to the instance, or a prototype object for a new volume.
Indicates whether deleting the instance will also delete the attached volume
Default:
false
The name for this volume attachment. The name must not be used by another volume attachment on the instance. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "delete_volume_on_instance_delete": true, "name": "my-volume-attachment-data-5iops", "volume": { "id": "d8b26921-1409-4c2f-9b46-39b5b6e0b945" } }'
options := &vpcv1.CreateInstanceVolumeAttachmentOptions{} options.SetInstanceID(instanceID) options.SetVolume(&vpcv1.VolumeIdentity{ ID: &volumeID, }) options.SetName(name) options.SetDeleteVolumeOnInstanceDelete(false) volumeAttachment, response, err := vpcService.CreateInstanceVolumeAttachment( options)
VolumeIdentityById volumeIdentityModel = new VolumeIdentityById.Builder() .id(id) .build(); CreateInstanceVolumeAttachmentOptions createInstanceVolumeAttachmentOptions = new CreateInstanceVolumeAttachmentOptions.Builder() .instanceId(instanceId) .name("my-volume-attachment") .volume(volumeIdentityModel) .build(); Response<VolumeAttachment> response = service.createInstanceVolumeAttachment(createInstanceVolumeAttachmentOptions).execute(); VolumeAttachment volumeAttachment = response.getResult();
const volumeIdentityModel = { id: volumeID, }; const params = { instanceId, volume: volumeIdentityModel, name: 'my-volume-attachment', deleteVolumeOnInstanceDelete: true, }; const response = await vpcService.createInstanceVolumeAttachment(params);
volume_identity_model = {} volume_identity_model['id'] = volume_id volume = volume_identity_model delete_volume_on_instance_delete = True name = 'my-volume-attachment' response = service.create_instance_volume_attachment( instance_id, volume, delete_volume_on_instance_delete=delete_volume_on_instance_delete, name=name, )
Response
The maximum bandwidth (in megabits per second) for the volume when attached to this instance. This may be lower than the volume bandwidth depending on the configuration of the instance.
Example:
250
The date and time that the volume was attached
Indicates whether deleting the instance will also delete the attached volume
The URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
The status of this volume attachment
Possible values: [
attached
,attaching
,deleting
,detaching
]The type of volume attachment
Possible values: [
boot
,data
]Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
Status Code
The volume attachment was created successfully, attaching the specified volume to the instance.
An invalid volume attachment prototype object was provided.
The volume attachment is not allowed to be created.
An instance with the specified identifier could not be found.
{ "bandwidth": 250, "created_at": "2019-02-28T16:35:47.000Z", "delete_volume_on_instance_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/9f2a645e-19c1-4f8f-b062-46b9e0671999", "id": "9f2a645e-19c1-4f8f-b062-46b9e0671999", "name": "my-volume-attachment-data-5iops", "status": "attached", "type": "data", "volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/d8b26921-1409-4c2f-9b46-39b5b6e0b945", "id": "d8b26921-1409-4c2f-9b46-39b5b6e0b945", "name": "my-volume-data-5iops", "resource_type": "volume" } }
Delete a volume attachment
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.
DELETE /instances/{instance_id}/volume_attachments/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The volume attachment identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceVolumeAttachmentOptions{} options.SetID(volumeID) options.SetInstanceID(instanceID) response, err := vpcService.DeleteInstanceVolumeAttachment(options)
DeleteInstanceVolumeAttachmentOptions deleteInstanceVolumeAttachmentOptions = new DeleteInstanceVolumeAttachmentOptions.Builder() .instanceId(instanceId) .id(id) .build(); Response<Void> response = service.deleteInstanceVolumeAttachment(deleteInstanceVolumeAttachmentOptions).execute();
const response = await vpcService.deleteInstanceVolumeAttachment({ instanceId, id, });
response = service.delete_instance_volume_attachment(instance_id, id)
Response
Status Code
The volume attachment was deleted successfully, detaching its volume from the instance.
The specified volume attachment cannot be deleted because its volume is busy.
The volume attachment is not allowed to be deleted.
A volume attachment with the specified identifier could not be found.
No Sample Response
Retrieve a volume attachment
This request retrieves a single volume attachment specified by the identifier in the URL.
GET /instances/{instance_id}/volume_attachments/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The volume attachment identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceVolumeAttachmentOptions{} options.SetInstanceID(instanceID) options.SetID(volumeID) volumeAttachment, response, err := vpcService.GetInstanceVolumeAttachment(options)
GetInstanceVolumeAttachmentOptions getInstanceVolumeAttachmentOptions = new GetInstanceVolumeAttachmentOptions.Builder() .instanceId(instanceId) .id(id) .build(); Response<VolumeAttachment> response = service.getInstanceVolumeAttachment(getInstanceVolumeAttachmentOptions).execute(); VolumeAttachment volumeAttachment = response.getResult();
const response = await vpcService.getInstanceVolumeAttachment({ instanceId, id, });
response = service.get_instance_volume_attachment(instance_id, id)
Response
The maximum bandwidth (in megabits per second) for the volume when attached to this instance. This may be lower than the volume bandwidth depending on the configuration of the instance.
Example:
250
The date and time that the volume was attached
Indicates whether deleting the instance will also delete the attached volume
The URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
The status of this volume attachment
Possible values: [
attached
,attaching
,deleting
,detaching
]The type of volume attachment
Possible values: [
boot
,data
]Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
Status Code
The volume attachment was retrieved successfully.
A volume attachment with the specified identifier could not be found for the specified instance.
{ "bandwidth": 250, "created_at": "2019-03-15T11:44:07.000Z", "delete_volume_on_instance_delete": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/8479a541-58ee-42ca-9efa-15a1551d42b9", "id": "8479a541-58ee-42ca-9efa-15a1551d42b9", "name": "my-data-volume-attachment", "status": "attached", "type": "data", "volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ca4b6df3-f5a8-4667-b5f2-f3b9b4160781", "id": "ca4b6df3-f5a8-4667-b5f2-f3b9b4160781", "name": "my-data-volume", "resource_type": "volume" } }
Update a volume attachment
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.
PATCH /instances/{instance_id}/volume_attachments/{id}
Request
Path Parameters
The virtual server instance identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The volume attachment identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The volume attachment patch
Indicates whether deleting the instance will also delete the attached volume
The name for this volume attachment. The name must not be used by another volume attachment on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume-attachment
curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "delete_volume_on_instance_delete": false, "name": "my-volume-attachment-data-5iops-updated" }'
options := &vpcv1.UpdateInstanceVolumeAttachmentOptions{} options.SetInstanceID(instanceID) options.SetID(volumeID) options.SetName(name) volumeAttachment, response, err := vpcService.UpdateInstanceVolumeAttachment( options)
UpdateInstanceVolumeAttachmentOptions updateInstanceVolumeAttachmentOptions = new UpdateInstanceVolumeAttachmentOptions.Builder() .instanceId(instanceId) .id(id) .name(name) .build(); Response<VolumeAttachment> response = service.updateInstanceVolumeAttachment(updateInstanceVolumeAttachmentOptions).execute(); VolumeAttachment volumeAttachment = response.getResult();
const params = { instanceId, id, deleteVolumeOnInstanceDelete: false, }; const response = await vpcService.updateInstanceVolumeAttachment(params);
delete_volume_on_instance_delete = True name = 'my-volume-attachment' response = service.update_instance_volume_attachment( instance_id, id, delete_volume_on_instance_delete=delete_volume_on_instance_delete, name=name, )
Response
The maximum bandwidth (in megabits per second) for the volume when attached to this instance. This may be lower than the volume bandwidth depending on the configuration of the instance.
Example:
250
The date and time that the volume was attached
Indicates whether deleting the instance will also delete the attached volume
The URL for this volume attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46f2-b1f1-bc152b2e391a/volume_attachments/0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
The status of this volume attachment
Possible values: [
attached
,attaching
,deleting
,detaching
]The type of volume attachment
Possible values: [
boot
,data
]Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.A unique identifier for the device which is exposed to the instance operating system
Example:
80b3e36e-41f4-40e9-bd56-beae81792a68
device
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
volume
Status Code
The volume attachment was updated successfully.
An invalid volume attachment patch was provided.
The volume attachment is not allowed to be updated.
A volume attachment with the specified identifier could not be found for the specified instance.
{ "bandwidth": 250, "created_at": "2019-02-28T16:35:47.000Z", "delete_volume_on_instance_delete": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/8f06378c-ed0e-481e-b98c-9a6dfbee1ed5/volume_attachments/9f2a645e-19c1-4f8f-b062-46b9e0671999", "id": "9f2a645e-19c1-4f8f-b062-46b9e0671999", "name": "my-volume-attachment-data-5iops-updated", "status": "attached", "type": "data", "volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/d8b26921-1409-4c2f-9b46-39b5b6e0b945", "id": "d8b26921-1409-4c2f-9b46-39b5b6e0b945", "name": "my-volume-data-5iops", "resource_type": "volume" } }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instance_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceGroupsOptions{} instanceGroups, response, err := vpcService.ListInstanceGroups(options)
ListInstanceGroupsOptions listInstanceGroupsOptions = new ListInstanceGroupsOptions.Builder() .build(); Response<InstanceGroupCollection> response = service.listInstanceGroups(listInstanceGroupsOptions).execute(); InstanceGroupCollection instanceGroupCollection = response.getResult();
const response = await vpcService.listInstanceGroups();
response = service.list_instance_groups(start=start, limit=limit)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups?limit=20
first
Collection of instance groups
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance groups were retrieved successfully.
{ "first": { "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups?limit=50" }, "instance_groups": [ { "created_at": "2020-12-29T19:55:00Z", "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60", "id": "r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60", "instance_template": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "name": "my-instance-template" }, "lifecycle_reasons": [], "lifecycle_state": "stable", "managers": [], "membership_count": 0, "name": "issuing-reverb-oblivion-seventh-perch-discover", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "healthy", "subnets": [ { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/subnets/07a7-3162c0fc-178f-46da-b4ca-d9448824056c", "id": "07a7-3162c0fc-178f-46da-b4ca-d9448824056c", "name": "my-subnet", "resource_type": "subnet" } ], "updated_at": "2020-10-29T19:55:00Z", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } } ], "limit": 50, "total_count": 1 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group prototype object
Instance template to use when creating new instances.
Instance groups are not compatible with instance templates that specify
true
fordefault_trusted_profile.auto_link
.The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
instance_template
The subnets to use when creating new instances.
subnets
The port to use for new load balancer pool members created by this instance group. The load balancer pool member will receive load balancer traffic on this port, unless the load balancer listener is using a port range. (Traffic received on a listener using a port range will be sent to members using the same port the listener received it on.)
This port will also be used for health checks unless the port property of
health_monitor
property is specified.This property must be specified if and only if
load_balancer_pool
has been specified.Possible values: 1 ≤ value ≤ 65535
Example:
22
The load balancer associated with the specified load balancer pool. Required if
load_balancer_pool
is specified. The load balancer must haveinstance_groups_supported
set totrue
.The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
load_balancer
If specified, this instance group will manage the load balancer pool. A pool member will be created for each instance created by this group. The specified load balancer pool must not be used by another instance group in the VPC.
If specified,
load_balancer
andapplication_port
must also be specified.The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
load_balancer_pool
The number of instances in the instance group
Possible values: 0 ≤ value ≤ 1000
Default:
0
Example:
10
The name for this instance group. The name must not be used by another instance group in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/instance_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "instance_template": { "id": "a6b1a881-2ce8-41a3-80fc-36316a73f803" }, "subnets": [ { "id": "7ec86020-1c6e-4889-b3f0-a15f2e50f87e" } ] }'
options := &vpcv1.CreateInstanceGroupOptions{} options.SetName(name) options.SetInstanceTemplate(instanceTemplateID) var subnetArray = []vpcv1.SubnetIdentityIntf{ &vpcv1.SubnetIdentity{ ID: &subnetId, }, } options.SetSubnets(subnetArray) instanceGroup, response, err := vpcService.CreateInstanceGroup(options)
InstanceTemplateIdentityById instanceTemplateIdentityModel = new InstanceTemplateIdentityById.Builder() .id(instanceTemplateId) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); CreateInstanceGroupOptions createInstanceGroupOptions = new CreateInstanceGroupOptions.Builder() .name("my-instance-group") .instanceTemplate(instanceTemplateIdentityModel) .subnets(new java.util.ArrayList<SubnetIdentity>(java.util.Arrays.asList(subnetIdentityModel))) .build(); Response<InstanceGroup> response = service.createInstanceGroup(createInstanceGroupOptions).execute(); InstanceGroup instanceGroup = response.getResult();
const params = { instanceTemplate: { id: instanceTemplateID, }, subnets: [{ id: subnetID, }], name: 'my-instance-group', membershipCount: 1, }; const response = await vpcService.createInstanceGroup(params);
instance_template_identity_model = {} instance_template_identity_model[ 'id'] = instance_template_id subnet_identity_model = {} subnet_identity_model['id'] = subnet_id load_balancer_identity_model = {} load_balancer_identity_model[ 'id'] = load_balancer_id load_balancer_pool_identity_model = {} load_balancer_pool_identity_model[ 'id'] = load_balancer_pool_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id instance_template = instance_template_identity_model subnets = [subnet_identity_model] name = 'my-instance-group' membership_count = 2 application_port = 22 load_balancer = load_balancer_identity_model load_balancer_pool = load_balancer_pool_identity_model resource_group = resource_group_identity_model
Response
The date and time that the instance group was created
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The template used to create new instances for this group.
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_template
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the instance group.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The managers for the instance group.
The number of instances in the instance group
Possible values: 0 ≤ value ≤ 1000
Example:
10
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group
- Examples:View
The status of the instance group
deleting
: Group is being deletedhealthy
: Group hasmembership_count
instancesscaling
: Instances in the group are being created or deleted to reachmembership_count
unhealthy
: Group is unable to reachmembership_count
instances
Possible values: [
deleting
,healthy
,scaling
,unhealthy
]The subnets to use when creating new instances.
Possible values: number of items ≥ 1
The date and time that the instance group was updated
The VPC the instance group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The port used for new load balancer pool members created by this instance group.
This property will be present if and only if
load_balancer_pool
is present.Possible values: 1 ≤ value ≤ 65535
Example:
22
If present, the load balancer pool this instance group manages. A pool member will be created for each instance created by this group.
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer_pool
Status Code
The instance group was created successfully.
An invalid instance group prototype object was provided.
The instance group prototype object specified in a load balancer pool that is already in use by another instance group in the VPC.
{ "$ref": "#/components/schemas/InstanceGroup/example" }
Delete an instance group
This request deletes an instance group. This operation cannot be reversed. Any instances associated with the group will be deleted.
DELETE /instance_groups/{id}
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupOptions{} options.SetID(id) response, err := vpcService.DeleteInstanceGroup(options)
DeleteInstanceGroupOptions deleteInstanceGroupOptions = new DeleteInstanceGroupOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteInstanceGroup(deleteInstanceGroupOptions).execute();
const response = await vpcService.deleteInstanceGroup({ id });
response = service.delete_instance_group(id)
Retrieve an instance group
This request retrieves a single instance group specified by identifier in the URL.
GET /instance_groups/{id}
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceGroupOptions{} options.SetID(id) instanceGroup, response, err := vpcService.GetInstanceGroup(options)
GetInstanceGroupOptions getInstanceGroupOptions = new GetInstanceGroupOptions.Builder() .id(id) .build(); Response<InstanceGroup> response = service.getInstanceGroup(getInstanceGroupOptions).execute(); InstanceGroup instanceGroup = response.getResult();
const response = await vpcService.getInstanceGroup({ id });
response = service.get_instance_group(id)
Response
The date and time that the instance group was created
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The template used to create new instances for this group.
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_template
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the instance group.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The managers for the instance group.
The number of instances in the instance group
Possible values: 0 ≤ value ≤ 1000
Example:
10
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group
- Examples:View
The status of the instance group
deleting
: Group is being deletedhealthy
: Group hasmembership_count
instancesscaling
: Instances in the group are being created or deleted to reachmembership_count
unhealthy
: Group is unable to reachmembership_count
instances
Possible values: [
deleting
,healthy
,scaling
,unhealthy
]The subnets to use when creating new instances.
Possible values: number of items ≥ 1
The date and time that the instance group was updated
The VPC the instance group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The port used for new load balancer pool members created by this instance group.
This property will be present if and only if
load_balancer_pool
is present.Possible values: 1 ≤ value ≤ 65535
Example:
22
If present, the load balancer pool this instance group manages. A pool member will be created for each instance created by this group.
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer_pool
Status Code
The instance group was retrieved successfully.
An instance group with the specified identifier could not be found.
{ "$ref": "#/components/schemas/InstanceGroup/example" }
Update an instance group
This request updates an instance group with the information provided instance group patch. The instance group patch object is structured in the same way as a retrieved instance group and contains only the information to be updated.
PATCH /instance_groups/{id}
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group patch
The port to use for new load balancer pool members created by this instance group.
This property must be set if and only if
load_balancer_pool
has been set.Possible values: 1 ≤ value ≤ 65535
Example:
22
Instance template to use when creating new instances.
Instance groups are not compatible with instance templates that specify
true
fordefault_trusted_profile.auto_link
.The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
instance_template
The load balancer associated with
load_balancer_pool
. The load balancer must haveinstance_groups_supported
set totrue
.This property must be set if and only if
load_balancer_pool
has been set.The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
load_balancer
If specified, this instance group will manage the load balancer pool. A pool member will be created for each instance created by this group. The specified load balancer pool must not be used by another instance group in the VPC.
If set,
load_balancer
andapplication_port
must also be set.The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
load_balancer_pool
The number of instances in the instance group
Possible values: 0 ≤ value ≤ 1000
Example:
10
The name for this instance group. The name must not be used by another instance group in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group
The subnets to use when creating new instances.
subnets
curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-group", "membership_count": 7 }'
options := &vpcv1.UpdateInstanceGroupOptions{} options.SetID(id) options.SetName(name) instanceGroup, response, err := vpcService.UpdateInstanceGroup(options)
UpdateInstanceGroupOptions updateInstanceGroupOptions = new UpdateInstanceGroupOptions.Builder() .id(id) .name(name) .build(); Response<InstanceGroup> response = service.updateInstanceGroup(updateInstanceGroupOptions).execute(); InstanceGroup instanceGroup = response.getResult();
const response = await vpcService.updateInstanceGroup({ id, name: 'my-instance-group', });
instance_template_identity_model = {} instance_template_identity_model[ 'id'] = instance_template_id subnet_identity_model = {} subnet_identity_model['id'] = subnet_id load_balancer_identity_model = {} load_balancer_identity_model[ 'id'] = load_balancer_id load_balancer_pool_identity_model = {} load_balancer_pool_identity_model[ 'id'] = load_balancer_pool_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id name = 'my-instance-group' membership_count = 3 subnets = [subnet_identity_model] application_port = 22 response = service.update_instance_group( id, name=name, membership_count=membership_count, instance_template=instance_template_identity_model, subnets=subnets, application_port=application_port, load_balancer=load_balancer_identity_model, load_balancer_pool=load_balancer_pool_identity_model)
Response
The date and time that the instance group was created
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The template used to create new instances for this group.
The CRN for this instance template
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-template:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance template
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance/templates/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance template
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a6b1a881-2ce8-41a3-80fc-36316a73f803
The name for this instance template. The name is unique across all instance templates in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-template
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_template
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the instance group.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The managers for the instance group.
The number of instances in the instance group
Possible values: 0 ≤ value ≤ 1000
Example:
10
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group
- Examples:View
The status of the instance group
deleting
: Group is being deletedhealthy
: Group hasmembership_count
instancesscaling
: Instances in the group are being created or deleted to reachmembership_count
unhealthy
: Group is unable to reachmembership_count
instances
Possible values: [
deleting
,healthy
,scaling
,unhealthy
]The subnets to use when creating new instances.
Possible values: number of items ≥ 1
The date and time that the instance group was updated
The VPC the instance group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The port used for new load balancer pool members created by this instance group.
This property will be present if and only if
load_balancer_pool
is present.Possible values: 1 ≤ value ≤ 65535
Example:
22
If present, the load balancer pool this instance group manages. A pool member will be created for each instance created by this group.
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer_pool
Status Code
The instance group was updated successfully.
An invalid instance group patch was provided.
The instance group is not allowed to be updated.
An instance group with the specified identifier could not be found.
The instance group patch object specified properties that cannot be changed while the instance group has memberships, or specified a load balancer pool that is already in use by another instance group in the VPC.
{ "$ref": "#/components/schemas/InstanceGroup/example" }
Delete an instance group load balancer
This request unbinds the instance group from the load balancer pool, and deletes the load balancer pool members.
DELETE /instance_groups/{instance_group_id}/load_balancer
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/load_balancer?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupLoadBalancerOptions{} options.SetInstanceGroupID(instanceGroupID) response, err := vpcService.DeleteInstanceGroupLoadBalancer(options)
DeleteInstanceGroupLoadBalancerOptions deleteInstanceGroupLoadBalancerOptions = new DeleteInstanceGroupLoadBalancerOptions.Builder() .instanceGroupId(instanceGroupId) .build(); Response<Void> response = service.deleteInstanceGroupLoadBalancer(deleteInstanceGroupLoadBalancerOptions).execute();
const response = await vpcService.deleteInstanceGroupLoadBalancer({ instanceGroupId, });
response = service.delete_instance_group_load_balancer(instance_group_id)
List all managers for an instance group
This request lists all managers for an instance group.
GET /instance_groups/{instance_group_id}/managers
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceGroupManagersOptions{} options.SetInstanceGroupID(instanceGroupID) instanceGroupManagers, response, err := vpcService.ListInstanceGroupManagers(options)
ListInstanceGroupManagersOptions listInstanceGroupManagersOptions = new ListInstanceGroupManagersOptions.Builder() .instanceGroupId(instanceGroupId) .build(); Response<InstanceGroupManagerCollection> response = service.listInstanceGroupManagers(listInstanceGroupManagersOptions).execute(); InstanceGroupManagerCollection instanceGroupManagerCollection = response.getResult();
const response = await vpcService.listInstanceGroupManagers({ instanceGroupId });
response = service.list_instance_group_managers(instance_group_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of instance group managers
managers
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance group managers were retrieved successfully.
An instance group with the specified identifier could not be found.
{ "first": { "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers?limit=50" }, "limit": 50, "managers": [ { "aggregation_window": 90, "cooldown": 300, "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "id": "r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "management_enabled": true, "manager_type": "autoscale", "max_membership_count": 5, "min_membership_count": 1, "name": "my-manager", "policies": [], "updated_at": "2020-10-29T19:54:00Z" } ], "total_count": 1 }
Create a manager for an instance group
This request creates a new instance group manager
POST /instance_groups/{instance_group_id}/managers
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager prototype object
Indicates whether this manager will control the instance group.
Default:
true
The name for this instance group manager. The name must not be used by another manager for the instance group. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group-manager
The type of instance group manager.
Allowable values: [
autoscale
]The maximum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The time window in seconds to aggregate metrics prior to evaluation
Possible values: 90 ≤ value ≤ 600
Default:
90
Example:
120
The duration of time in seconds to pause further scale actions after scaling has taken place
Possible values: 120 ≤ value ≤ 3600
Default:
300
Example:
210
The minimum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Default:
1
Example:
10
One of
curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "manager_type": "autoscale", "max_membership_count": 50 }'
prototype := &vpcv1.InstanceGroupManagerPrototype{ ManagerType: "autoscale", MaxMembershipCount: 50, } options := &vpcv1.CreateInstanceGroupManagerOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerPrototype(prototype) instanceGroupManager, response, err := vpcService.CreateInstanceGroupManager(options)
InstanceGroupManagerPrototypeInstanceGroupManagerAutoScalePrototype instanceGroupManagerPrototypeModel = new InstanceGroupManagerPrototypeInstanceGroupManagerAutoScalePrototype.Builder() .name("my-instance-group-manager") .maxMembershipCount(Long.valueOf("10")) .managerType("autoscale") .build(); CreateInstanceGroupManagerOptions createInstanceGroupManagerOptions = new CreateInstanceGroupManagerOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerPrototype(instanceGroupManagerPrototypeModel) .build(); Response<InstanceGroupManager> response = service.createInstanceGroupManager(createInstanceGroupManagerOptions).execute(); InstanceGroupManager instanceGroupManager = response.getResult();
const instanceGroupManagerPrototypeModel = { name: 'my-instance-group-manager', management_enabled: true, aggregation_window: 120, cooldown: 210, max_membership_count: 2, min_membership_count: 3, manager_type: 'autoscale', }; const params = { instanceGroupId, instanceGroupManagerPrototype: instanceGroupManagerPrototypeModel, }; const response = await vpcService.createInstanceGroupManager(params);
instance_group_manager_prototype_model = {} instance_group_manager_prototype_model[ 'name'] = 'my-instance-group-manager' instance_group_manager_prototype_model['management_enabled'] = True instance_group_manager_prototype_model['aggregation_window'] = 120 instance_group_manager_prototype_model['cooldown'] = 210 instance_group_manager_prototype_model['max_membership_count'] = 10 instance_group_manager_prototype_model['min_membership_count'] = 10 instance_group_manager_prototype_model['manager_type'] = 'autoscale' response = service.create_instance_group_manager( instance_group_id, instance_group_manager_prototype_model)
Response
The date and time that the instance group manager was created
The URL for this instance group manager
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a/managers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this instance group manager
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
Indicates whether this manager will control the instance group.
The name for this instance group manager. The name is unique across all managers for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager
The date and time that the instance group manager was updated
The time window in seconds to aggregate metrics prior to evaluation
Possible values: 90 ≤ value ≤ 600
Example:
120
The duration of time in seconds to pause further scale actions after scaling has taken place
Possible values: 120 ≤ value ≤ 3600
Example:
210
The type of instance group manager.
Possible values: [
autoscale
]The maximum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The minimum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The policies of the instance group manager
One of
Status Code
The instance group manager was created successfully.
An invalid instance group manager prototype object was provided.
{ "aggregation_window": 90, "cooldown": 300, "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "id": "r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "management_enabled": true, "manager_type": "autoscale", "max_membership_count": 50, "min_membership_count": 1, "name": "my-manager", "policies": [], "updated_at": "2020-10-29T19:54:00Z" }
Delete an instance group manager
This request deletes an instance group manager. This operation cannot be reversed.
DELETE /instance_groups/{instance_group_id}/managers/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupManagerOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) response, err := vpcService.DeleteInstanceGroupManager(options)
DeleteInstanceGroupManagerOptions deleteInstanceGroupManagerOptions = new DeleteInstanceGroupManagerOptions.Builder() .instanceGroupId(instanceGroupId) .id(id) .build(); Response<Void> response = service.deleteInstanceGroupManager(deleteInstanceGroupManagerOptions).execute();
const response = await vpcService.deleteInstanceGroupManager({ instanceGroupId, id, });
response = service.delete_instance_group_manager(instance_group_id, id)
Retrieve an instance group manager
This request retrieves a single instance group manager specified by identifier in the URL.
GET /instance_groups/{instance_group_id}/managers/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceGroupManagerOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) instanceGroupManager, response, err := vpcService.GetInstanceGroupManager(options)
GetInstanceGroupManagerOptions getInstanceGroupManagerOptions = new GetInstanceGroupManagerOptions.Builder() .instanceGroupId(instanceGroupId) .id(managerId) .build(); Response<InstanceGroupManager> response = service.getInstanceGroupManager(getInstanceGroupManagerOptions).execute(); InstanceGroupManager instanceGroupManager = response.getResult();
const response = await vpcService.getInstanceGroupManager({ instanceGroupId, id });
response = service.get_instance_group_manager(instance_group_id, id)
Response
The date and time that the instance group manager was created
The URL for this instance group manager
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a/managers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this instance group manager
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
Indicates whether this manager will control the instance group.
The name for this instance group manager. The name is unique across all managers for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager
The date and time that the instance group manager was updated
The time window in seconds to aggregate metrics prior to evaluation
Possible values: 90 ≤ value ≤ 600
Example:
120
The duration of time in seconds to pause further scale actions after scaling has taken place
Possible values: 120 ≤ value ≤ 3600
Example:
210
The type of instance group manager.
Possible values: [
autoscale
]The maximum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The minimum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The policies of the instance group manager
One of
Status Code
The instance group manager was retrieved successfully.
An instance group manager with the specified identifier could not be found.
{ "aggregation_window": 90, "cooldown": 300, "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "id": "r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "management_enabled": true, "manager_type": "autoscale", "max_membership_count": 5, "min_membership_count": 1, "name": "my-manager", "policies": [], "updated_at": "2020-10-29T19:54:00Z" }
Update an instance group manager
This request updates an instance group manager with the information provided instance group manager patch.
PATCH /instance_groups/{instance_group_id}/managers/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager patch
The time window in seconds to aggregate metrics prior to evaluation
Possible values: 90 ≤ value ≤ 600
Example:
120
The duration of time in seconds to pause further scale actions after scaling has taken place
Possible values: 120 ≤ value ≤ 3600
Example:
210
Indicates whether this manager will control the instance group.
The maximum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The minimum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The name for this instance group manager. The name must not be used by another manager for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group-manager
curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "min_membership_count": 10, "max_membership_count": 20 }'
options := &vpcv1.UpdateInstanceGroupManagerOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) options.SetMaxMembershipCount(20) instanceGroupManager, response, err := vpcService.UpdateInstanceGroupManager(options)
UpdateInstanceGroupManagerOptions updateInstanceGroupManagerOptions = new UpdateInstanceGroupManagerOptions.Builder() .instanceGroupId(instanceGroupId) .id(managerId) .maxMembershipCount(Long.valueOf("10")) .build(); Response<InstanceGroupManager> response = service.updateInstanceGroupManager(updateInstanceGroupManagerOptions).execute(); InstanceGroupManager instanceGroupManager = response.getResult();
const response = await vpcService.updateInstanceGroupManager({ instanceGroupId, id, cooldown: 240, });
name = 'my-instance-group-manager' management_enabled = True aggregation_window = 120 cooldown = 210 max_membership_count = 10 min_membership_count = 10 response = service.update_instance_group_manager( instance_group_id, id, name=name, management_enabled=management_enabled, aggregation_window=aggregation_window, cooldown=cooldown, max_membership_count=max_membership_count, min_membership_count=min_membership_count)
Response
The date and time that the instance group manager was created
The URL for this instance group manager
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a/managers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this instance group manager
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
Indicates whether this manager will control the instance group.
The name for this instance group manager. The name is unique across all managers for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager
The date and time that the instance group manager was updated
The time window in seconds to aggregate metrics prior to evaluation
Possible values: 90 ≤ value ≤ 600
Example:
120
The duration of time in seconds to pause further scale actions after scaling has taken place
Possible values: 120 ≤ value ≤ 3600
Example:
210
The type of instance group manager.
Possible values: [
autoscale
]The maximum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The minimum number of members in a managed instance group
Possible values: 1 ≤ value ≤ 1000
Example:
10
The policies of the instance group manager
One of
Status Code
The instance group manager was updated successfully.
An invalid instance group manager patch was provided.
The instance group manager is not allowed to be updated.
An instance group manager with the specified identifier could not be found.
{ "aggregation_window": 90, "cooldown": 300, "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "id": "r018-4f2f7036-86b0-4d1b-a729-12357d45b00f", "management_enabled": true, "manager_type": "autoscale", "max_membership_count": 10, "min_membership_count": 20, "name": "my-manager", "policies": [], "updated_at": "2020-10-29T19:55:00Z" }
List all actions for an instance group manager
This request lists all instance group actions for an instance group manager.
GET /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/actions
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceGroupManagerActionsOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) instanceGroupManagerActions, response, err := vpcService.ListInstanceGroupManagerActions(options)
ListInstanceGroupManagerActionsOptions listInstanceGroupManagerActionsOptions = new ListInstanceGroupManagerActionsOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .build(); Response<InstanceGroupManagerActionsCollection> response = service.listInstanceGroupManagerActions(listInstanceGroupManagerActionsOptions).execute(); InstanceGroupManagerActionsCollection instanceGroupManagerActionsCollection = response.getResult();
const response = await vpcService.listInstanceGroupManagerActions({ instanceGroupId, instanceGroupManagerId, });
response = service.list_instance_group_manager_actions( instance_group_id, instance_group_manager_id)
Response
Collection of instance group manager actions
actions
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/actions?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/actions?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance group manager actions were retrieved successfully.
An instance group manager with the specified identifier could not be found.
{ "actions": [ { "action_type": "scheduled", "auto_delete": true, "auto_delete_timeout": 24, "created_at": "2020-10-29T19:54:00Z", "group": { "membership_count": 1 }, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/actions/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "name": "my-action", "resource_type": "instance_group_manager_action", "status": "active", "updated_at": "2020-10-29T19:54:00Z" } ], "first": { "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/actions?limit=50" }, "limit": 50, "total_count": 1 }
Create an instance group manager action
This request creates a new instance group manager action
POST /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/actions
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager action prototype object
The name for this instance group manager action. The name must not be used by another action for the instance group manager. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-action
One of
curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "metric_type": "cpu", "metric_value": 50, "action_type": "scheduled" }'
instanceGroupManagerScheduledActionGroupPrototypeModel := &vpcv1.InstanceGroupManagerScheduledActionByManagerManager{ ID: &managerID, } name := "my-instance-group-manager-action" dateTime := "2021-06-01T12:00:00.000Z" instanceGroupManagerActionPrototype := &vpcv1.InstanceGroupManagerActionPrototype{ Name: &name, RunAt: &dateTime, Manager: instanceGroupManagerScheduledActionGroupPrototypeModel, } options := &vpcv1.CreateInstanceGroupManagerActionOptions options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.InstanceGroupManagerActionPrototype = &instanceGroupManagerActionPrototype instanceGroupManagerAction, response, err := vpcService.CreateInstanceGroupManagerAction(options)
import com.ibm.cloud.sdk.core.util.DateUtils; InstanceGroupManagerScheduledActionByManagerManager instanceGroupManagerScheduledActionByManagerManager = new InstanceGroupManagerScheduledActionByManagerManager.Builder() .id(managerID) .build(); InstanceGroupManagerActionPrototypeScheduledActionPrototypeByRunAtByManager instanceGroupManagerActionPrototypeModel = new InstanceGroupManagerActionPrototypeScheduledActionPrototypeByRunAtByManager.Builder() .name("my-instance-group-manager-action") .runAt(DateUtils.parseAsDateTime("2021-06-01T12:00:00.000Z")) .manager(instanceGroupManagerScheduledActionByManagerManager) .build(); CreateInstanceGroupManagerActionOptions createInstanceGroupManagerActionOptions = new CreateInstanceGroupManagerActionOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .build(); Response<InstanceGroupManagerAction> response = service.createInstanceGroupManagerAction(createInstanceGroupManagerActionOptions).execute(); InstanceGroupManagerAction instanceGroupManagerAction = response.getResult();
const instanceGroupManagerScheduledActionGroupPrototypeModel = { id: managerID, }; const instanceGroupManagerActionPrototypeModel = { name: 'my-instance-group-manager-action', run_at: '2021-06-01T12:00:00.000Z', manager: instanceGroupManagerScheduledActionGroupPrototypeModel, }; const params = { instanceGroupId, instanceGroupManagerId, instanceGroupManagerActionPrototype: instanceGroupManagerActionPrototypeModel, }; const response = await vpcService.createInstanceGroupManagerAction(params);
instance_group_manager_scheduled_action_group_prototype_model = {} instance_group_manager_scheduled_action_group_prototype_model['id'] = managerID instance_group_manager_action_prototype_model = {} instance_group_manager_action_prototype_model['name'] = 'my-instance-group-manager-action' instance_group_manager_action_prototype_model['run_at'] = '2021-06-01T12:00:00.000Z' instance_group_manager_action_prototype_model['manager'] = instance_group_manager_scheduled_action_group_prototype_model instance_group_manager_action = service.create_instance_group_manager_action( instance_group_id, instance_group_manager_id, instance_group_manager_action_prototype_model)
Response
Indicates whether this scheduled action will be automatically deleted after it has completed and
auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
auto_delete
istrue
, and this scheduled action has finished, the hours after which it will be automatically deleted. If the value is0
, the action will be deleted once it has finished. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 744
Example:
24
The date and time that the instance group manager action was created
The URL for this instance group manager action
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/actions/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager action
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager action. The name is unique across all actions for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-action
The resource type
Possible values: [
instance_group_manager_action
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the instance group action
active
: Action is ready to be runcompleted
: Action was completed successfullyfailed
: Action could not be completed successfullyincompatible
: Action parameters are not compatible with the group or manageromitted
: Action was not applied because this action's manager was disabled
Possible values: [
active
,completed
,failed
,incompatible
,omitted
]The date and time that the instance group manager action was updated
The type of action for the instance group
Possible values: [
scheduled
]The cron specification for a recurring scheduled action. Actions can be applied a maximum of one time within a 5 min period.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The date and time the scheduled action was last applied. If absent, the action has never been applied.
The date and time the scheduled action will next run. If absent, the system is currently calculating the next run time.
One of
Status Code
The instance group manager action was created successfully.
An invalid instance group manager action prototype object was provided.
{ "action_type": "scheduled", "auto_delete": true, "auto_delete_timeout": 24, "created_at": "2020-10-29T19:54:00Z", "group": { "membership_count": 1 }, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/actions/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "name": "my-action", "resource_type": "instance_group_manager_action", "status": "active", "updated_at": "2020-10-29T19:54:00Z" }
Delete specified instance group manager action
This request deletes an instance group manager action. This operation cannot be reversed.
DELETE /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/actions/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager action identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupManagerActionOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) response, err := vpcService.DeleteInstanceGroupManagerAction(options)
DeleteInstanceGroupManagerActionOptions deleteInstanceGroupManagerActionOptions = new DeleteInstanceGroupManagerActionOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(instanceGroupManagerId) .id(id) .build(); Response<Void> response = service.deleteInstanceGroupManagerAction(deleteInstanceGroupManagerActionOptions).execute();
const response = await vpcService.deleteInstanceGroupManagerAction({ instanceGroupId, instanceGroupManagerId, id, });
response = service.delete_instance_group_manager_action( instance_group_id, instance_group_manager_id, id)
Retrieve specified instance group manager action
This request retrieves a single instance group manager action specified by identifier in the URL.
GET /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/actions/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager action identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceGroupManagerActionOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) instanceGroupManagerAction, response, err := vpcService.GetInstanceGroupManagerAction(options)
GetInstanceGroupManagerActionOptions getInstanceGroupManagerActionOptions = new GetInstanceGroupManagerActionOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .id(id) .build(); Response<InstanceGroupManagerAction> response = service.getInstanceGroupManagerAction(getInstanceGroupManagerActionOptions).execute(); InstanceGroupManagerAction instanceGroupManagerAction = response.getResult();
const response = await vpcService.getInstanceGroupManagerAction({ instanceGroupId, instanceGroupManagerId, id, });
response = service.get_instance_group_manager_action( instance_group_id, instance_group_manager_id, id)
Response
Indicates whether this scheduled action will be automatically deleted after it has completed and
auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
auto_delete
istrue
, and this scheduled action has finished, the hours after which it will be automatically deleted. If the value is0
, the action will be deleted once it has finished. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 744
Example:
24
The date and time that the instance group manager action was created
The URL for this instance group manager action
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/actions/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager action
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager action. The name is unique across all actions for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-action
The resource type
Possible values: [
instance_group_manager_action
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the instance group action
active
: Action is ready to be runcompleted
: Action was completed successfullyfailed
: Action could not be completed successfullyincompatible
: Action parameters are not compatible with the group or manageromitted
: Action was not applied because this action's manager was disabled
Possible values: [
active
,completed
,failed
,incompatible
,omitted
]The date and time that the instance group manager action was updated
The type of action for the instance group
Possible values: [
scheduled
]The cron specification for a recurring scheduled action. Actions can be applied a maximum of one time within a 5 min period.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The date and time the scheduled action was last applied. If absent, the action has never been applied.
The date and time the scheduled action will next run. If absent, the system is currently calculating the next run time.
One of
Status Code
The instance group manager action was retrieved successfully.
An instance group manager action with the specified identifier could not be found.
{ "action_type": "scheduled", "auto_delete": true, "auto_delete_timeout": 24, "created_at": "2020-10-29T19:54:00Z", "group": { "membership_count": 1 }, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/actions/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "name": "my-action", "resource_type": "instance_group_manager_action", "status": "active", "updated_at": "2020-10-29T19:54:00Z" }
Update specified instance group manager action
This request updates an instance group manager action.
PATCH /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/actions/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager action identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager action patch
The cron specification for a recurring scheduled action. Actions can be applied a maximum of one time within a 5 min period.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The name for this instance group manager action. The name must not be used by another action for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-action
The date and time the scheduled action will run
curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "metric_type": "cpu", "metric_value": 50 }'
name := "my-instance-group-manager-action-updated" instanceGroupManagerActionPatchModel := &vpcv1.InstanceGroupManagerActionPatch{} instanceGroupManagerActionPatchModel.Name := &name instanceGroupManagerActionPatch, _ := instanceGroupManagerActionPatchModel.AsPatch() options := &vpcv1.UpdateInstanceGroupManagerActionOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) options.InstanceGroupManagerActionPatch = instanceGroupManagerActionPatch instanceGroupManagerAction, response, err := vpcService.UpdateInstanceGroupManagerAction(options)
InstanceGroupManagerActionPatch instanceGroupManagerActionPatchModel = new InstanceGroupManagerActionPatch.Builder() .name("my-instance-group-manager-action-updated") .build(); Map<String, Object> instanceGroupManagerActionPatchModelAsPatch = instanceGroupManagerActionPatchModel.asPatch(); UpdateInstanceGroupManagerActionOptions updateInstanceGroupManagerActionOptions = new UpdateInstanceGroupManagerActionOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .id(id) .instanceGroupManagerActionPatch(instanceGroupManagerActionPatchModelAsPatch) .build(); Response<InstanceGroupManagerAction> response = service.updateInstanceGroupManagerAction(updateInstanceGroupManagerActionOptions).execute(); InstanceGroupManagerAction instanceGroupManagerAction = response.getResult();
const instanceGroupManagerActionPatchModel = { name: 'my-instance-group-manager-action-updated', }; const params = { instanceGroupId, instanceGroupManagerId, id, instanceGroupManagerActionPatch: instanceGroupManagerActionPatch, }; const response = await vpcService.updateInstanceGroupManagerAction(params);
instance_group_manager_action_patch_model = {} instance_group_manager_action_patch_model['name'] = 'my-instance-group-manager-action-updated' instance_group_manager_action = service.update_instance_group_manager_action( instance_group_id, instance_group_manager_id, id, instance_group_manager_action_patch=instance_group_manager_action_patch_model)
Response
Indicates whether this scheduled action will be automatically deleted after it has completed and
auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
auto_delete
istrue
, and this scheduled action has finished, the hours after which it will be automatically deleted. If the value is0
, the action will be deleted once it has finished. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 744
Example:
24
The date and time that the instance group manager action was created
The URL for this instance group manager action
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/actions/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager action
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager action. The name is unique across all actions for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-action
The resource type
Possible values: [
instance_group_manager_action
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the instance group action
active
: Action is ready to be runcompleted
: Action was completed successfullyfailed
: Action could not be completed successfullyincompatible
: Action parameters are not compatible with the group or manageromitted
: Action was not applied because this action's manager was disabled
Possible values: [
active
,completed
,failed
,incompatible
,omitted
]The date and time that the instance group manager action was updated
The type of action for the instance group
Possible values: [
scheduled
]The cron specification for a recurring scheduled action. Actions can be applied a maximum of one time within a 5 min period.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The date and time the scheduled action was last applied. If absent, the action has never been applied.
The date and time the scheduled action will next run. If absent, the system is currently calculating the next run time.
One of
Status Code
The instance group manager action was updated successfully.
An invalid instance group manager action patch was provided.
The instance group manager action is not allowed to be updated.
An instance group manager action with the specified identifier could not be found.
{ "action_type": "scheduled", "auto_delete": true, "auto_delete_timeout": 24, "created_at": "2020-10-29T19:54:00Z", "group": { "membership_count": 1 }, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/actions/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "name": "my-action", "resource_type": "instance_group_manager_action", "status": "active", "updated_at": "2020-10-29T19:55:00Z" }
List all policies for an instance group manager
This request lists all policies for an instance group manager.
GET /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/policies
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceGroupManagerPoliciesOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) instanceGroupManagerPolicies, response, err := vpcService.ListInstanceGroupManagerPolices(options)
ListInstanceGroupManagerPoliciesOptions listInstanceGroupManagerPoliciesOptions = new ListInstanceGroupManagerPoliciesOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .build(); Response<InstanceGroupManagerPolicyCollection> response = service.listInstanceGroupManagerPolicies(listInstanceGroupManagerPoliciesOptions).execute(); InstanceGroupManagerPolicyCollection instanceGroupManagerPolicyCollection = response.getResult();
const response = await vpcService.listInstanceGroupManagerPolicies({ instanceGroupId, instanceGroupManagerId, });
response = service.list_instance_group_manager_policies( instance_group_id, instance_group_manager_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/policies?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of instance group manager policies
policies
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/policies?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance group manager policies were retrieved successfully.
An instance group manager with the specified identifier could not be found.
{ "first": { "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/policies?limit=50" }, "limit": 50, "policies": [ { "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/policies/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "metric_type": "cpu", "metric_value": 50, "name": "my-policy", "policy_type": "target", "updated_at": "2020-10-29T19:54:00Z" } ], "total_count": 1 }
Create a policy for an instance group manager
This request creates a new instance group manager policy
POST /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/policies
Request
Path Parameters
The instance group identifier
The instance group manager identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager policy prototype object
The name for this instance group manager policy. The name must not be used by another policy for the instance group manager. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group-manager-policy
The type of metric to be evaluated
Allowable values: [
cpu
,memory
,network_in
,network_out
]The metric value to be evaluated
The type of policy for the instance group
Allowable values: [
target
]
One of
curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "manager_type": "scheduled", "metric_type": "cpu", "metric_value": 50, "policy_type": "target" }'
prototype := &vpcv1.InstanceGroupManagerPolicyPrototype{ PolicyType: "target", MetricType: "cpu", MetricValue: 20, } options := &vpcv1.CreateInstanceGroupManagerPolicyOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetInstanceGroupManagerPolicyPrototype(prototype) instanceGroupManagerPolicy, response, err := vpcService.CreateInstanceGroupManagerPolicy(options)
InstanceGroupManagerPolicyPrototypeInstanceGroupManagerTargetPolicyPrototype instanceGroupManagerPolicyPrototypeModel = new InstanceGroupManagerPolicyPrototypeInstanceGroupManagerTargetPolicyPrototype.Builder() .name("my-instance-group-manager-policy") .metricType("cpu") .metricValue(Long.valueOf("85")) .policyType("target") .build(); CreateInstanceGroupManagerPolicyOptions createInstanceGroupManagerPolicyOptions = new CreateInstanceGroupManagerPolicyOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .instanceGroupManagerPolicyPrototype(instanceGroupManagerPolicyPrototypeModel) .build(); Response<InstanceGroupManagerPolicy> response = service.createInstanceGroupManagerPolicy(createInstanceGroupManagerPolicyOptions).execute(); InstanceGroupManagerPolicy instanceGroupManagerPolicy = response.getResult();
const params = { instanceGroupId, instanceGroupManagerId, instanceGroupManagerPolicyPrototype: { metric_type: 'cpu', metric_value: 38, policy_type: 'target', }, }; const response = await vpcService.createInstanceGroupManagerPolicy(params);
instance_group_manager_policy_prototype_model = {} instance_group_manager_policy_prototype_model[ 'name'] = 'my-instance-group-manager-policy' instance_group_manager_policy_prototype_model['metric_type'] = 'cpu' instance_group_manager_policy_prototype_model['metric_value'] = 38 instance_group_manager_policy_prototype_model['policy_type'] = 'target' instance_group_manager_policy_prototype = instance_group_manager_policy_prototype_model response = service.create_instance_group_manager_policy( instance_group_id, instance_group_manager_id, instance_group_manager_policy_prototype)
Response
The date and time that the instance group manager policy was created
The URL for this instance group manager policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/policies/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager policy. The name is unique across all policies for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-policy
The date and time that the instance group manager policy was updated
The type of metric to be evaluated
Possible values: [
cpu
,memory
,network_in
,network_out
]The metric value to be evaluated
The type of policy for the instance group
Possible values: [
target
]
One of
Status Code
The instance group manager policy was created successfully.
An invalid instance group manager policy prototype object was provided.
{ "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/policies/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "metric_type": "cpu", "metric_value": 50, "name": "my-policy", "policy_type": "target", "updated_at": "2020-10-29T19:54:00Z" }
Delete an instance group manager policy
This request deletes an instance group manager policy. This operation cannot be reversed.
DELETE /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/policies/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupManagerPolicyOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) response, err := vpcService.DeleteInstanceGroupManagerPolicy(options)
DeleteInstanceGroupManagerPolicyOptions deleteInstanceGroupManagerPolicyOptions = new DeleteInstanceGroupManagerPolicyOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .id(id) .build(); Response<Void> response = service.deleteInstanceGroupManagerPolicy(deleteInstanceGroupManagerPolicyOptions).execute();
const response = await vpcService.deleteInstanceGroupManagerPolicy({ instanceGroupId, instanceGroupManagerId, id, });
response = service.delete_instance_group_manager_policy( instance_group_id, instance_group_manager_id, id)
Retrieve an instance group manager policy
This request retrieves a single instance group manager policy specified by identifier in the URL.
GET /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/policies/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceGroupManagerPolicyOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) instanceGroupManagerPolicy, response, err := vpcService.GetInstanceGroupManagerPolicy(options)
GetInstanceGroupManagerPolicyOptions getInstanceGroupManagerPolicyOptions = new GetInstanceGroupManagerPolicyOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .id(policyId) .build(); Response<InstanceGroupManagerPolicy> response = service.getInstanceGroupManagerPolicy(getInstanceGroupManagerPolicyOptions).execute(); InstanceGroupManagerPolicy instanceGroupManagerPolicy = response.getResult();
const response = await vpcService.getInstanceGroupManagerPolicy({ instanceGroupId, instanceGroupManagerId, id, });
response = service.get_instance_group_manager_policy( instance_group_id, instance_group_manager_id, id)
Response
The date and time that the instance group manager policy was created
The URL for this instance group manager policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/policies/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager policy. The name is unique across all policies for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-policy
The date and time that the instance group manager policy was updated
The type of metric to be evaluated
Possible values: [
cpu
,memory
,network_in
,network_out
]The metric value to be evaluated
The type of policy for the instance group
Possible values: [
target
]
One of
Status Code
The instance group manager policy was retrieved successfully.
An instance group manager policy with the specified identifier could not be found.
{ "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/policies/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "metric_type": "cpu", "metric_value": 50, "name": "my-policy", "policy_type": "target", "updated_at": "2020-10-29T19:54:00Z" }
Update an instance group manager policy
This request updates an instance group manager policy.
PATCH /instance_groups/{instance_group_id}/managers/{instance_group_manager_id}/policies/{id}
Request
Path Parameters
The instance group identifier
The instance group manager identifier
The instance group manager policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group manager policy patch
The type of metric to be evaluated
Allowable values: [
cpu
,memory
,network_in
,network_out
]The metric value to be evaluated
The name for this instance group manager policy. The name must not be used by another policy for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group-manager-policy
curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "metric_type": "cpu", "metric_value": 50 }'
options := &vpcv1.UpdateInstanceGroupManagerPolicyOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetInstanceGroupManagerID(instanceGroupManagerID) options.SetID(id) options.SetMetricValue(50) instanceGroupManagerPolicy, response, err := vpcService.UpdateInstanceGroupManagerPolicy(options)
UpdateInstanceGroupManagerPolicyOptions updateInstanceGroupManagerPolicyOptions = new UpdateInstanceGroupManagerPolicyOptions.Builder() .instanceGroupId(instanceGroupId) .instanceGroupManagerId(managerId) .id(policyId) .metricValue(Long.valueOf("85")) .build(); Response<InstanceGroupManagerPolicy> response = service.updateInstanceGroupManagerPolicy(updateInstanceGroupManagerPolicyOptions).execute(); InstanceGroupManagerPolicy instanceGroupManagerPolicy = response.getResult();
const params = { instanceGroupId, instanceGroupManagerId, id, metric_type: 'cpu', metric_value: 33, }; const response = await vpcService.updateInstanceGroupManagerPolicy(params);
name = 'my-instance-group-manager-policy' metric_type = 'cpu' metric_value = 38 response = service.update_instance_group_manager_policy( instance_group_id, instance_group_manager_id, id, name=name, metric_type=metric_type, metric_value=metric_value)
Response
The date and time that the instance group manager policy was created
The URL for this instance group manager policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/managers/4c939b00-601f-11ea-bca2-000c29475bed/policies/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group manager policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group manager policy. The name is unique across all policies for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-manager-policy
The date and time that the instance group manager policy was updated
The type of metric to be evaluated
Possible values: [
cpu
,memory
,network_in
,network_out
]The metric value to be evaluated
The type of policy for the instance group
Possible values: [
target
]
One of
Status Code
The instance group manager policy was updated successfully.
An invalid instance group manager policy patch was provided.
The instance group manager policy is not allowed to be updated.
An instance group manager policy with the specified identifier could not be found.
{ "created_at": "2020-10-29T19:54:00Z", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/managers/r018-4f2f7036-86b0-4d1b-a729-12357d45b00f/policies/r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "id": "r018-02d7b6c3-e3c8-4569-ba6a-caa5d4d6146c", "metric_type": "cpu", "metric_value": 50, "name": "my-policy", "policy_type": "target", "updated_at": "2020-10-29T19:55:00Z" }
Delete all memberships from an instance group
This request deletes all memberships of an instance group. This operation cannot be reversed.
reversed. Any memberships that have delete_instance_on_membership_delete
set to true
will
also have their instances deleted.
DELETE /instance_groups/{instance_group_id}/memberships
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupMembershipsOptions{} options.SetInstanceGroupID(instanceGroupID) response, err := vpcService.DeleteInstanceGroupMemberships(options)
DeleteInstanceGroupMembershipsOptions deleteInstanceGroupMembershipsOptions = new DeleteInstanceGroupMembershipsOptions.Builder() .instanceGroupId(instanceGroupId) .build(); Response<Void> response = service.deleteInstanceGroupMemberships(deleteInstanceGroupMembershipsOptions).execute();
const response = await vpcService.deleteInstanceGroupMemberships({ instanceGroupId, });
response = service.delete_instance_group_memberships(instance_group_id)
List all memberships for an instance group
This request lists all instance group memberships for an instance group.
GET /instance_groups/{instance_group_id}/memberships
Request
Path Parameters
The instance group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListInstanceGroupMembershipsOptions{} options.SetInstanceGroupID(instanceGroupID) instanceGroupMemberships, response, err := vpcService.ListInstanceGroupMemberships(options)
ListInstanceGroupMembershipsOptions listInstanceGroupMembershipsOptions = new ListInstanceGroupMembershipsOptions.Builder() .instanceGroupId(instanceGroupId) .build(); Response<InstanceGroupMembershipCollection> response = service.listInstanceGroupMemberships(listInstanceGroupMembershipsOptions).execute(); InstanceGroupMembershipCollection instanceGroupMembershipCollection = response.getResult();
const response = await vpcService.listInstanceGroupMemberships({ instanceGroupId });
response = service.list_instance_group_memberships(instance_group_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/7241e2a8-601f-11ea-8503-000c29475bed/memberships?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of instance group memberships
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/7241e2a8-601f-11ea-8503-000c29475bed/memberships?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The instance group memberships were retrieved successfully.
An instance group with the specified identifier could not be found.
{ "first": { "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/memberships?limit=50" }, "limit": 50, "memberships": [ { "created_at": "2020-10-29T19:54:00Z", "delete_instance_on_membership_delete": true, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/memberships/04977d01-89c0-488b-a599-3d0dc32880e7", "id": "04977d01-89c0-488b-a599-3d0dc32880e7", "instance": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "id": "07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "name": "issuing-reverb-oblivion-seventh-perch-discove-rjg8mt3dv9-g1e60" }, "instance_template": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "name": "my-instance-template" }, "name": "my-membership-1", "status": "healthy", "updated_at": "2020-10-29T19:54:00Z" }, { "created_at": "2020-10-29T19:54:00Z", "delete_instance_on_membership_delete": true, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/memberships/0335f610-0e31-470e-b092-e5ea5ee79e41", "id": "0335f610-0e31-470e-b092-e5ea5ee79e41", "instance": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/07a7_11c592d4-ed11-45f6-91fd-fc3918e4d77d", "id": "07a7_11c592d4-ed11-45f6-91fd-fc3918e4d77d", "name": "issuing-reverb-oblivion-seventh-perch-discove-tq6ek486jb-kz8o8" }, "instance_template": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "name": "my-instance-template-2" }, "name": "my-membership-2", "status": "healthy", "updated_at": "2020-10-29T19:54:00Z" } ], "total_count": 2 }
Delete an instance group membership
This request deletes a memberships of an instance group. This operation cannot be reversed.
reversed. If the membership has delete_instance_on_membership_delete
set to true
, the
instance will also be deleted.
DELETE /instance_groups/{instance_group_id}/memberships/{id}
Request
Path Parameters
The instance group identifier
The instance group membership identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteInstanceGroupMembershipOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) response, err := vpcService.DeleteInstanceGroupMembership(options)
DeleteInstanceGroupMembershipOptions deleteInstanceGroupMembershipOptions = new DeleteInstanceGroupMembershipOptions.Builder() .instanceGroupId(instanceGroupId) .id(id) .build(); Response<Void> response = service.deleteInstanceGroupMembership(deleteInstanceGroupMembershipOptions).execute();
const response = await vpcService.deleteInstanceGroupMembership({ instanceGroupId, id, });
response = service.delete_instance_group_membership(instance_group_id, id)
Retrieve an instance group membership
This request retrieves a single instance group membership specified by identifier in the URL.
GET /instance_groups/{instance_group_id}/memberships/{id}
Request
Path Parameters
The instance group identifier
The instance group membership identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetInstanceGroupMembershipOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) instanceGroupMembership, response, err := vpcService.GetInstanceGroupMembership(options)
GetInstanceGroupMembershipOptions getInstanceGroupMembershipOptions = new GetInstanceGroupMembershipOptions.Builder() .instanceGroupId(instanceGroupId) .id(id) .build(); Response<InstanceGroupMembership> response = service.getInstanceGroupMembership(getInstanceGroupMembershipOptions).execute(); InstanceGroupMembership instanceGroupMembership = response.getResult();
const response = await vpcService.getInstanceGroupMembership({ instanceGroupId, id, });
response = service.get_instance_group_membership(instance_group_id, id)
Response
The date and time that the instance group manager policy was created
If set to true, when deleting the membership the instance will also be deleted
The URL for this instance group membership
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a/memberships/8b002d86-601f-11ea-898b-000c29475bed
The unique identifier for this instance group membership
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
- Examples:View
The name for this instance group membership. The name is unique across all memberships for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-membership
The status of the instance group membership
deleting
: Membership is deleting dependent resourcesfailed
: Membership was unable to maintain dependent resourceshealthy
: Membership is active and serving in the grouppending
: Membership is waiting for dependent resourcesunhealthy
: Membership has unhealthy dependent resources
Possible values: [
deleting
,failed
,healthy
,pending
,unhealthy
]The date and time that the instance group membership was updated
Status Code
The instance group membership was retrieved successfully.
An instance group membership with the specified identifier could not be found.
{ "created_at": "2020-10-29T19:54:00Z", "delete_instance_on_membership_delete": true, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/memberships/04977d01-89c0-488b-a599-3d0dc32880e7", "id": "04977d01-89c0-488b-a599-3d0dc32880e7", "instance": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "id": "07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "name": "issuing-reverb-oblivion-seventh-perch-discove-rjg8mt3dv9-g1e60" }, "instance_template": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "name": "my-instance-template" }, "name": "my-membership", "status": "healthy", "updated_at": "2020-10-29T19:54:00Z" }
Update an instance group membership
This request updates an instance group membership with the information provided instance group membership patch.
PATCH /instance_groups/{instance_group_id}/memberships/{id}
Request
Path Parameters
The instance group identifier
The instance group membership identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The instance group membership patch
The name for this instance group membership. The name must not be used by another membership for the instance group manager.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-instance-group-membership
curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-instance-group-membership" }'
options := &vpcv1.UpdateInstanceGroupMembershipOptions{} options.SetInstanceGroupID(instanceGroupID) options.SetID(id) options.SetName("my-instance-group-membership") instanceGroupMembership, response, err := vpcService.UpdateInstanceGroupMembership(options)
UpdateInstanceGroupMembershipOptions updateInstanceGroupMembershipOptions = new UpdateInstanceGroupMembershipOptions.Builder() .instanceGroupId(instanceGroupId) .id(id) .name(name) .build(); Response<InstanceGroupMembership> response = service.updateInstanceGroupMembership(updateInstanceGroupMembershipOptions).execute(); InstanceGroupMembership instanceGroupMembership = response.getResult();
const response = await vpcService.updateInstanceGroupMembership({ instanceGroupId, id, });
response = service.update_instance_group_membership(instance_group_id, id, name=new_name)
Response
The date and time that the instance group manager policy was created
If set to true, when deleting the membership the instance will also be deleted
The URL for this instance group membership
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a/memberships/8b002d86-601f-11ea-898b-000c29475bed
The unique identifier for this instance group membership
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
- Examples:View
The name for this instance group membership. The name is unique across all memberships for the instance group.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group-membership
The status of the instance group membership
deleting
: Membership is deleting dependent resourcesfailed
: Membership was unable to maintain dependent resourceshealthy
: Membership is active and serving in the grouppending
: Membership is waiting for dependent resourcesunhealthy
: Membership has unhealthy dependent resources
Possible values: [
deleting
,failed
,healthy
,pending
,unhealthy
]The date and time that the instance group membership was updated
Status Code
The instance group membership was updated successfully.
An invalid instance group membership patch was provided.
The instance group membership is not allowed to be updated.
An instance group membership with the specified identifier could not be found.
{ "created_at": "2020-10-29T19:54:00Z", "delete_instance_on_membership_delete": true, "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance_groups/r018-7b3ac170-01f3-43d6-87ec-f0ed11ed3f60/memberships/04977d01-89c0-488b-a599-3d0dc32880e7", "id": "04977d01-89c0-488b-a599-3d0dc32880e7", "instance": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instances/07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "id": "07a7_2bc064dc-f463-46dc-9825-ee6aa2e37927", "name": "issuing-reverb-oblivion-seventh-perch-discove-rjg8mt3dv9-g1e60" }, "instance_template": { "crn": "crn:[...]", "href": "https://eu-gb.iaas.cloud.ibm.com/v1/instance/templates/07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "id": "07a7-eca9fd45-e086-4400-a799-77b09ec5be84", "name": "my-instance-template" }, "name": "my-instance-group-membership", "status": "healthy", "updated_at": "2020-10-29T19:55:00Z" }
List all reservations
This request lists all reservations in the region. A reservation provides reserved capacity for a specified profile in a specified zone. A reservation can also include a long-term committed use discount.
The reservations will be sorted by their created_at
property values, with newest
reservations first. Reservations with identical created_at
property values will in turn
be sorted by ascending name
property values.
GET /reservations
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
curl -X GET "$vpc_api_endpoint/v1/reservations?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listReservationsOptions := &vpcv1.ListReservationsOptions{} reservations, resp, err := vpcService.ListReservations(listReservationsOptions)
ListReservationsOptions listReservationsOptions = new ListReservationsOptions.Builder() .build(); Response<ReservationCollection> response = service.listReservations(listReservationsOptions).execute(); ReservationCollection reservationCollection = response.getResult();
const response = await vpcService.listReservations();
reservation_collection = vpc_service.list_reservations().get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of reservations
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The reservations were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations?limit=50" }, "limit": 50, "reservations": [ { "affinity_policy": "restricted", "capacity": { "allocated": 10, "available": 2, "status": "allocated", "total": 10, "used": 8 }, "committed_use": { "expiration_at": "2024-12-29T19:55:00.000Z", "expiration_policy": "renew", "term": "one_year" }, "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "lifecycle_state": "stable", "name": "my-reservation", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "name": "bx2-2x8", "resource_type": "instance_profile" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "reservation", "status": "active", "status_reasons": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "total_count": 1 }
Create a reservation
This request creates a new reservation from a reservation prototype object. The prototype object is structured in the same way as a retrieved reservation, and contains the information necessary to create the new reservation.
POST /reservations
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The reservation prototype object
The capacity reservation configuration to use.
The committed use configuration to use for this reservation.
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The specified value must be listed in the
reservation_terms
in the profile for this reservation.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Allowable values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
release
committed_use
The profile to use for this reservation.
The zone to use for this reservation.
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The affinity policy to use for this reservation:
restricted
: The reservation must be manually requested
Allowable values: [
restricted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
restricted
The name for this reservation. The name must not be used by another reservation in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/reservations?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "capacity": { "total": 10 }, "committed_use": { "expiration_policy": "renew", "term": "one_year" }, "name": "my-reservation", "profile": { "name": "bx2-4x16", "resource_type": "instance_profile" }, "zone": { "name": "us-south-1" } }'
reservationCapacityPrototypeModel := &vpcv1.ReservationCapacityPrototype{ Total: &total, } reservationCommittedUsePrototypeModel := &vpcv1.ReservationCommittedUsePrototype{ Term: &term, } reservationProfilePrototypeModel := &vpcv1.ReservationProfilePrototype{ Name: &profileName, ResourceType: &resourceType, } zoneIdentityModel := &vpcv1.ZoneIdentityByName{ Name: &zoneName, } createReservationOptions := &vpcv1.CreateReservationOptions{ Capacity: reservationCapacityPrototypeModel, CommittedUse: reservationCommittedUsePrototypeModel, Profile: reservationProfilePrototypeModel, Zone: zoneIdentityModel, } reservation, response, err := vpcService.CreateReservation(createReservationOptions)
ReservationCapacityPrototype reservationCapacityPrototypeModel = new ReservationCapacityPrototype.Builder() .total(total) .build(); ReservationCommittedUsePrototype reservationCommittedUsePrototypeModel = new ReservationCommittedUsePrototype.Builder() .term(term) .build(); ReservationProfilePrototype reservationProfilePrototypeModel = new ReservationProfilePrototype.Builder() .name(profileName) .resourceType(resourceType) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateReservationOptions createReservationOptions = new CreateReservationOptions.Builder() .capacity(reservationCapacityPrototypeModel) .committedUse(reservationCommittedUsePrototypeModel) .profile(reservationProfilePrototypeModel) .zone(zoneIdentityModel) .name("my-reservation") .build(); Response<Reservation> response = vpcService.createReservation(createReservationOptions).execute(); Reservation reservation = response.getResult();
const reservationCapacityModel = { total: total, }; const reservationCommittedUseModel = { term: term, }; const reservationProfileModel = { name: profileName, resource_type: resourceType, }; const vpcIdentityModel = { id: vpcId, }; const zoneIdentityModel = { name: zoneName, }; const params = { capacity: reservationCapacityModel, committedUse: reservationCommittedUseModel, profile: reservationProfileModel, zone: zoneIdentityModel, name: "my-reservation", }; const response = await vpcService.createReservation(params);
capacity_model = {} capacity_model['total'] = total committed_use_model = {} committed_use_model['term'] = term profile_model = {} profile_model['name'] = profileName profile_model['resource_type'] = resourceType zone_identity_model = {} zone_identity_model['name'] = zoneName reservation = vpc_service.create_reservation( capacity=capacity_model, committed_use=committed_use_model, profile=profile_model, zone=zone_identity_model, name='my-reservation').get_result()
Response
The affinity policy to use for this reservation:
restricted
: The reservation must be manually requested
The enumerated values for this property may expand in the future.
Possible values: [
restricted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the reservation was created
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The lifecycle state of this reservation
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The profile for this reservation.
Examples:ViewThe resource group for this reservation
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the reservation.
The enumerated values for this property may expand in the future.
Possible values: [
activating
,active
,deactivating
,expired
,failed
,inactive
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The zone for this reservation.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The capacity configuration for this reservation
If absent, this reservation has no assigned capacity.
The committed use configuration for this reservation.
If absent, this reservation has no commitment for use.
The expiration date and time for this committed use reservation.
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Possible values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The enumerated values for this property may expand in the future.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
committed_use
Status Code
The reservation was created successfully.
An invalid reservation prototype object was provided.
{ "affinity_policy": "restricted", "capacity": { "allocated": 10, "available": 2, "status": "allocated", "total": 10, "used": 8 }, "committed_use": { "expiration_at": "2024-12-29T19:55:00.000Z", "expiration_policy": "renew", "term": "one_year" }, "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "lifecycle_state": "pending", "name": "my-reservation", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "name": "bx2-2x8", "resource_type": "instance_profile" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "reservation", "status": "active", "status_reasons": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a reservation
This request deletes a reservation. This operation cannot be reversed. Reservations with
a status
of active
are not allowed to be deleted.
DELETE /reservations/{id}
Request
Path Parameters
The reservation identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/reservations/$id?version=2024-04-30&generation=2&maturity=beta" - H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteReservationOptions{ ID: &reservationID, } reservation, response, err := vpcService.DeleteReservation(options)
DeleteReservationOptions deleteReservationOptions = new DeleteReservationOptions.Builder() .id(reservationId) .build(); Response<Reservation> response = vpcService.deleteReservation(deleteReservationOptions).execute(); Reservation reservation = response.getResult();
const params = { id: reservationId, } const response = await vpcService.deleteReservation(params);
reservation = vpc_service.delete_reservation(id=reservation_id).get_result()
Response
The affinity policy to use for this reservation:
restricted
: The reservation must be manually requested
The enumerated values for this property may expand in the future.
Possible values: [
restricted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the reservation was created
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The lifecycle state of this reservation
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The profile for this reservation.
Examples:ViewThe resource group for this reservation
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the reservation.
The enumerated values for this property may expand in the future.
Possible values: [
activating
,active
,deactivating
,expired
,failed
,inactive
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The zone for this reservation.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The capacity configuration for this reservation
If absent, this reservation has no assigned capacity.
The committed use configuration for this reservation.
If absent, this reservation has no commitment for use.
The expiration date and time for this committed use reservation.
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Possible values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The enumerated values for this property may expand in the future.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
committed_use
Status Code
The reservation deletion request was accepted.
The reservation is not allowed to be deleted.
A reservation with the specified identifier could not be found.
{ "affinity_policy": "restricted", "capacity": { "allocated": 10, "available": 2, "status": "allocated", "total": 10, "used": 8 }, "committed_use": { "expiration_at": "2024-12-29T19:55:00.000Z", "expiration_policy": "renew", "term": "one_year" }, "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "lifecycle_state": "deleting", "name": "my-reservation", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "name": "bx2-2x8", "resource_type": "instance_profile" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "reservation", "status": "active", "status_reasons": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Retrieve a reservation
This request retrieves a single reservation specified by identifier in the URL.
GET /reservations/{id}
Request
Path Parameters
The reservation identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/reservations/$id?version=2024-04-30&generation=2&maturity=beta" - H "Authorization: Bearer $iam_token"
options := &vpcv1.GetReservationOptions{ ID: &reservationID, } reservation, response, err := vpcService.GetReservation(options)
GetReservationOptions getReservationOptions = new GetReservationOptions.Builder() .id(reservationId) .build(); Response<Reservation> response = vpcService.getReservation(getReservationOptions).execute(); Reservation reservation = response.getResult();
const params = { id: reservationId, }; const response = await vpcService.getReservation(params);
reservation = vpc_service.get_reservation(id=reservation_id).get_result()
Response
The affinity policy to use for this reservation:
restricted
: The reservation must be manually requested
The enumerated values for this property may expand in the future.
Possible values: [
restricted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the reservation was created
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The lifecycle state of this reservation
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The profile for this reservation.
Examples:ViewThe resource group for this reservation
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the reservation.
The enumerated values for this property may expand in the future.
Possible values: [
activating
,active
,deactivating
,expired
,failed
,inactive
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The zone for this reservation.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The capacity configuration for this reservation
If absent, this reservation has no assigned capacity.
The committed use configuration for this reservation.
If absent, this reservation has no commitment for use.
The expiration date and time for this committed use reservation.
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Possible values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The enumerated values for this property may expand in the future.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
committed_use
Status Code
The reservation was retrieved successfully.
A reservation with the specified identifier could not be found.
{ "affinity_policy": "restricted", "capacity": { "allocated": 10, "available": 2, "status": "allocated", "total": 10, "used": 8 }, "committed_use": { "expiration_at": "2024-12-29T19:55:00.000Z", "expiration_policy": "renew", "term": "one_year" }, "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "lifecycle_state": "stable", "name": "my-reservation", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "name": "bx2-2x8", "resource_type": "instance_profile" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "reservation", "status": "active", "status_reasons": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a reservation
This request updates a reservation with the information provided in a reservation patch object. The patch object is structured in the same way as a retrieved reservation and needs to contain only the information to be updated.
PATCH /reservations/{id}
Request
Path Parameters
The reservation identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The reservation patch
The capacity reservation configuration to use.
The configuration can only be changed for reservations with a
status
ofinactive
.The committed use configuration to use for this reservation.
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Allowable values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The specified value must be listed in the
reservation_terms
in the profile for this reservation. The term can only be changed for a reservation with astatus
ofinactive
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
committed_use
The name for this reservation. The name must not be used by another reservation in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The profile to use for this reservation.
The profile can only be changed for a reservation with a
status
ofinactive
.
curl -X PATCH "$vpc_api_endpoint/v1/reservations/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "committed_use": { "expiration_policy": "release" } }'
reservationPatchModel := new(vpcv1.ReservationPatch) reservationPatchModel.Name = &updatedName reservationPatchModelAsPatch, asPatchErr := reservationPatchModel.AsPatch()
ReservationPatch reservationPatchModel = new ReservationPatch.Builder() .build(); Map<String, Object> reservationPatchModelAsPatch = reservationPatchModel.asPatch(); UpdateReservationOptions updateReservationOptions = new UpdateReservationOptions.Builder() .id(reservationId) .reservationPatch(reservationPatchModelAsPatch) .build(); Response<Reservation> response = vpcService.updateReservation(updateReservationOptions).execute(); Reservation reservation = response.getResult();
const params = { id: reservationId, name: 'my-reservation-updated', } const response = await vpcService.updateReservation(params);
reservation_patch_model = {} reservation_patch_model['name'] ='my-reservation-updated' reservation = vpc_service.update_reservation( id=reservation_id, reservation_patch=reservation_patch_model).get_result()
Response
The affinity policy to use for this reservation:
restricted
: The reservation must be manually requested
The enumerated values for this property may expand in the future.
Possible values: [
restricted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the reservation was created
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The URL for this reservation
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
7187-ba49df72-37b8-43ac-98da-f8e029de0e63
The lifecycle state of this reservation
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The profile for this reservation.
Examples:ViewThe resource group for this reservation
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the reservation.
The enumerated values for this property may expand in the future.
Possible values: [
activating
,active
,deactivating
,expired
,failed
,inactive
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The zone for this reservation.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The capacity configuration for this reservation
If absent, this reservation has no assigned capacity.
The committed use configuration for this reservation.
If absent, this reservation has no commitment for use.
The expiration date and time for this committed use reservation.
The policy to apply when the committed use term expires:
release
: Release any available capacity and let the reservation expire.renew
: Renew for another term, provided the term remains listed in thereservation_terms
for the profile. Otherwise, let the reservation expire.
The enumerated values for this property may expand in the future.
Possible values: [
release
,renew
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The term for this committed use reservation:
one_year
: 1 yearthree_year
: 3 years
The enumerated values for this property may expand in the future.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
committed_use
Status Code
The reservation was updated successfully.
An invalid reservation patch was provided.
A reservation with the specified identifier could not be found.
{ "affinity_policy": "restricted", "capacity": { "allocated": 10, "available": 2, "status": "allocated", "total": 10, "used": 8 }, "committed_use": { "expiration_at": "2024-12-29T19:55:00.000Z", "expiration_policy": "renew", "term": "one_year" }, "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/reservations/7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "7187-ba49df72-37b8-43ac-98da-f8e029de0e63", "lifecycle_state": "stable", "name": "my-reservation-updated", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/bx2-2x8", "name": "bx2-2x8", "resource_type": "instance_profile" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "reservation", "status": "active", "status_reasons": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Activate a reservation
This request activates a reservation. For this request to succeed, the reservation status
must be inactive
.
POST /reservations/{id}/activate
Request
Path Parameters
The reservation identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/reservations/$id/activate?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ActivateReservationOptions{ ID: &reservationID, } response, err := vpcService.ActivateReservation(options)
ActivateReservationOptions activateReservationOptions = new ActivateReservationOptions.Builder() .id(reservationId) .build(); Response<Void> response = vpcService.activateReservation(activateReservationOptions).execute();
const params = { id: reservationId, } const response = await vpcService.activateReservation(params);
response = vpc_service.activate_reservation(id=reservation_id).get_result()
List all dedicated host groups
This request lists all dedicated host groups in the region. Host groups are a collection of dedicated hosts for placement of instances. Each dedicated host must belong to one and only one group. Host groups do not span zones.
GET /dedicated_host/groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
Filters the collection to resources with a
name
property matching the exact specified name.
curl -X GET "$vpc_api_endpoint/v1/dedicated_host/groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListDedicatedHostGroupsOptions() dedicatedHostGroups, response, err := vpcService.ListDedicatedHostGroups(options)
ListDedicatedHostGroupsOptions listDedicatedHostGroupsOptions = new ListDedicatedHostGroupsOptions.Builder() .build(); Response<DedicatedHostGroupCollection> response = service.listDedicatedHostGroups(listDedicatedHostGroupsOptions).execute(); DedicatedHostGroupCollection dedicatedHostGroupCollection = response.getResult();
const response = await vpcService.listDedicatedHostGroups();
response = service.list_dedicated_host_groups() dedicated_host_groups = response.get_result()['dedicated_host_groups']
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups?limit=20
first
Collection of dedicated host groups
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The dedicated host groups were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups?limit=50" }, "groups": [ { "class": "mx2", "created_at": "2020-06-23T21:29:25Z", "crn": "crn:[...]", "dedicated_hosts": [], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-97e0a56f-9d6e-426b-8ebe-22aacfa47e9a", "id": "0787-97e0a56f-9d6e-426b-8ebe-22aacfa47e9a", "name": "pamphlet-subatomic-paging-vividly-emblaze-skies", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host_group", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }, { "class": "mx2", "created_at": "2020-04-14T16:53:28Z", "crn": "crn:[...]", "dedicated_hosts": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "name": "test-new", "resource_type": "dedicated_host" } ], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host_group", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "limit": 50, "total_count": 2 }
Create a dedicated host group
This request creates a new dedicated host group.
POST /dedicated_host/groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The dedicated host group prototype object
The dedicated host profile class for hosts in this group
Example:
mx2
The dedicated host profile family for hosts in this group
Allowable values: [
balanced
,compute
,memory
]Example:
balanced
The zone this dedicated host group will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-host-group
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/dedicated_host/groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-host-group", "family": "memory", "class": "mx2", "zone": { "name": "us-south-1" } }'
options := &vpcv1.CreateDedicatedHostGroupOptions{ Name: &name, Class: &class, Family: &family, Zone: &vpcv1.ZoneIdentity{ Name: &zoneName, }, } dedicatedHostGroup, response, err = vpcService.CreateDedicatedHostGroup(options)
ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateDedicatedHostGroupOptions createDedicatedHostGroupOptions = new CreateDedicatedHostGroupOptions.Builder() .name('my-dedicated-host-group') .xClass(className) .family(familyName) .zone(zoneIdentityModel) .build(); Response<DedicatedHostGroup> response = service.createDedicatedHostGroup(createDedicatedHostGroupOptions).execute(); DedicatedHostGroup dedicatedHostGroup = response.getResult();
const params = { _class: className, family: familyName, name: 'my-dedicated-host-group', zone: { id: zoneID }, }; const response = await vpcService.createDedicatedHostGroup(params);
zone_identity_model = {} zone_identity_model['name'] = zoneName class_ = 'mx2' family = 'balanced' zone = zone_identity_model response = service.create_dedicated_host_group( class_, family, zone)
Response
The dedicated host profile class for hosts in this group
Example:
mx2
The date and time that the dedicated host group was created
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The dedicated hosts that are in this dedicated host group
The dedicated host profile family for hosts in this group
Possible values: [
balanced
,compute
,memory
]Example:
balanced
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource group for this dedicated host group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The instance profiles usable by instances placed on this dedicated host group.
Possible values: number of items ≥ 1
The zone this dedicated host group resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host group was created successfully.
An invalid dedicated host group prototype object was provided
{ "class": "mx2", "created_at": "2020-06-23T21:29:25Z", "crn": "crn:[...]", "dedicated_hosts": [], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-97e0a56f-9d6e-426b-8ebe-22aacfa47e9a", "id": "0787-97e0a56f-9d6e-426b-8ebe-22aacfa47e9a", "name": "pamphlet-subatomic-paging-vividly-emblaze-skies", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host_group", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a dedicated host group
This request deletes a dedicated host group.
DELETE /dedicated_host/groups/{id}
Request
Path Parameters
The dedicated host group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/dedicated_host/groups/$dedicated_host_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteDedicatedHostGroupOptions(id) response, err := vpcService.DeleteDedicatedHostGroup(options)
DeleteDedicatedHostGroupOptions deleteDedicatedHostGroupOptions = new DeleteDedicatedHostGroupOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteDedicatedHostGroup(deleteDedicatedHostGroupOptions).execute();
const response = await vpcService.deleteDedicatedHostGroup({ id });
response = service.delete_dedicated_host_group(id)
Retrieve a dedicated host group
This request retrieves a single dedicated host group specified by the identifier in the URL.
GET /dedicated_host/groups/{id}
Request
Path Parameters
The dedicated host group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/dedicated_host/groups/$dedicated_host_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetDedicatedHostGroupOptions(id) dedicatedHostGroup, response, err := vpcService.GetDedicatedHostGroup(options)
GetDedicatedHostGroupOptions getDedicatedHostGroupOptions = new GetDedicatedHostGroupOptions.Builder() .id(id) .build(); Response<DedicatedHostGroup> response = service.getDedicatedHostGroup(getDedicatedHostGroupOptions).execute(); DedicatedHostGroup dedicatedHostGroup = response.getResult();
const response = await vpcService.getDedicatedHostGroup({ id });
response = service.get_dedicated_host_group(id) if response.status_code == 200: dedicated_host_group = response.get_result()
Response
The dedicated host profile class for hosts in this group
Example:
mx2
The date and time that the dedicated host group was created
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The dedicated hosts that are in this dedicated host group
The dedicated host profile family for hosts in this group
Possible values: [
balanced
,compute
,memory
]Example:
balanced
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource group for this dedicated host group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The instance profiles usable by instances placed on this dedicated host group.
Possible values: number of items ≥ 1
The zone this dedicated host group resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host group was retrieved successfully.
A dedicated host group with the specified identifier could not be found.
{ "class": "mx2", "created_at": "2020-04-14T16:53:28Z", "crn": "crn:[...]", "dedicated_hosts": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "name": "test-new", "resource_type": "dedicated_host" } ], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default", "resource_type": "dedicated_host" }, "resource_type": "dedicated_host_group", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a dedicated host group
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.
PATCH /dedicated_host/groups/{id}
Request
Path Parameters
The dedicated host group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The dedicated host group patch
The name for this dedicated host group. The name must not be used by another dedicated host group in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-host-group
curl -X PATCH "$vpc_api_endpoint/v1/dedicated_host/groups/$dedicated_host_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-host-group-updated" }'
options := &vpcv1.UpdateDedicatedHostGroupOptions{ DedicatedHostGroupID: &id, Name: &name, } dedicatedHostGroup, response, err := vpcService.UpdateDedicatedHostGroup(options)
UpdateDedicatedHostGroupOptions updateDedicatedHostGroupOptions = new UpdateDedicatedHostGroupOptions.Builder() .id(id) .name("my-dedicated-host-group-update") .build(); Response<DedicatedHostGroup> response = service.updateDedicatedHostGroup(updateDedicatedHostGroupOptions).execute(); DedicatedHostGroup dedicatedHostGroup = response.getResult();
const response = await vpcService.updateDedicatedHostGroup({ id, name: 'my-dedicated-host-group', });
new_name = 'my-dedicated-host-group-updated' response = service.update_dedicated_host_group(id, name=new_name)
Response
The dedicated host profile class for hosts in this group
Example:
mx2
The date and time that the dedicated host group was created
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The dedicated hosts that are in this dedicated host group
The dedicated host profile family for hosts in this group
Possible values: [
balanced
,compute
,memory
]Example:
balanced
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource group for this dedicated host group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The instance profiles usable by instances placed on this dedicated host group.
Possible values: number of items ≥ 1
The zone this dedicated host group resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host group was updated successfully.
An invalid dedicated host group patch was provided.
A dedicated host group with the specified identifier could not be found.
The dedicated host group must be empty to change family
{ "class": "mx2", "created_at": "2020-04-14T16:53:28Z", "crn": "crn:[...]", "dedicated_hosts": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "name": "test-new", "resource_type": "dedicated_host" } ], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "my-host-group-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host_group", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all 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.
GET /dedicated_host/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/dedicated_host/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListDedicatedHostProfilesOptions{} profiles, response, err := vpcService.ListDedicatedHostProfiles(options)
ListDedicatedHostProfilesOptions listDedicatedHostProfilesOptions = new ListDedicatedHostProfilesOptions(); Response<DedicatedHostProfileCollection> response = service.listDedicatedHostProfiles(listDedicatedHostProfilesOptions).execute(); DedicatedHostProfileCollection dedicatedHostProfileCollection = response.getResult();
const response = await vpcService.listDedicatedHostProfiles();
response = service.list_dedicated_host_profiles()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of dedicated host profiles
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles?start=9da91&limit=20
next
Status Code
The dedicated host profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles?limit=50" }, "limit": 50, "profiles": [ { "class": "mx2", "disks": [], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/mx2-host-152x1216", "memory": { "type": "fixed", "value": 1216 }, "name": "mx2-host-152x1216", "resource_type": "dedicated_host_profile", "socket_count": { "type": "fixed", "value": 4 }, "status": "current", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 152 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } } ], "total_count": 1 }
Retrieve a dedicated host profile
This request retrieves a single dedicated host profile specified by the name in the URL.
GET /dedicated_host/profiles/{name}
Request
Path Parameters
The dedicated host profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/dedicated_host/profiles/$profile_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetDedicatedHostProfileOptions{} options.SetName(profileName) profile, response, err := vpcService.GetDedicatedHostProfile(options)
GetDedicatedHostProfileOptions getDedicatedHostProfileOptions = new GetDedicatedHostProfileOptions.Builder() .name(profileName) .build(); Response<DedicatedHostProfile> response = service.getDedicatedHostProfile(getDedicatedHostProfileOptions).execute(); DedicatedHostProfile dedicatedHostProfile = response.getResult();
const response = await vpcService.getDedicatedHostProfile({ name: profileName });
response = service.get_dedicated_host_profile(name)
Response
The product class this dedicated host profile belongs to
Example:
mx2
Collection of the dedicated host profile's disks
Possible values: number of items ≥ 0
The product family this dedicated host profile belongs to
The enumerated values for this property may expand in the future.
Possible values: [
balanced
,compute
,memory
]Example:
balanced
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The globally unique name for this dedicated host profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mx2-host-152x1216
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] (https://cloud.ibm.com/docs/vpc?topic=vpc-dh-profiles&interface=ui#profiles-naming-rule) for information on how generations are defined within a dedicated host profile.
The enumerated values for this property may expand in the future.
Possible values: [
current
,previous
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
current
The instance profiles usable by instances placed on dedicated hosts with this profile.
Possible values: number of items ≥ 1
Status Code
The dedicated host profile was retrieved successfully
A dedicated host profile with the specified name could not be found.
{ "class": "mx2", "disks": [], "family": "memory", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/mx2-host-152x1216", "memory": { "type": "fixed", "value": 1216 }, "name": "mx2-host-152x1216", "resource_type": "dedicated_host_profile", "socket_count": { "type": "fixed", "value": 4 }, "status": "previous", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu_architecture": { "type": "fixed", "value": "amd64" }, "vcpu_count": { "type": "fixed", "value": 152 }, "vcpu_manufacturer": { "type": "fixed", "value": "intel" } }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to dedicated hosts with a
group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
Filters the collection to resources with a
name
property matching the exact specified name.
curl -X GET "$vpc_api_endpoint/v1/dedicated_hosts?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListDedicatedHostsOptions() dedicatedHosts, response, err := vpcService.ListDedicatedHosts(options)
ListDedicatedHostsOptions listDedicatedHostsOptions = new ListDedicatedHostsOptions.Builder() .build(); Response<DedicatedHostCollection> response = service.listDedicatedHosts(listDedicatedHostsOptions).execute(); DedicatedHostCollection dedicatedHostCollection = response.getResult();
const response = await vpcService.listDedicatedHosts();
response = service.list_dedicated_hosts() dedicated_hosts = response.get_result()['dedicated_hosts']
Response
Collection of dedicated hosts
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The dedicated hosts were retrieved successfully.
{ "dedicated_hosts": [ { "available_memory": 346, "available_vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "created_at": "2020-05-29T19:38:33Z", "crn": "crn:[...]", "disks": [], "group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_type": "dedicated_host_group" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "instance_placement_enabled": false, "instances": [], "lifecycle_state": "stable", "memory": 346, "name": "test-new", "numa": { "count": 0, "nodes": [] }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/dh2-56x344", "name": "dh2-56x344" }, "provisionable": true, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host", "socket_count": 2, "state": "available", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts?limit=50" }, "limit": 50, "total_count": 1 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The dedicated host prototype object
The profile to use for this dedicated host
The globally unique name for this dedicated host profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mx2-host-152x1216
profile
If set to true, instances can be placed on this dedicated host
Default:
true
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-host
The resource group to use. If unspecified, the account's default resource group will be used.
The dedicated host group for this dedicated host
One of
curl -X POST "$vpc_api_endpoint/v1/dedicated_hosts?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-host", "zone": { "name": "us-south-1" }, "group": { "id": "0c8eccb4-271c-4518-956c-32bfce5cf83b" }, "profile": { "name": "dh2-56x448" } }'
options := &vpcv1.CreateDedicatedHostOptions{} options.SetDedicatedHostPrototype(&vpcv1.DedicatedHostPrototype{ Name: &name, Profile: &vpcv1.DedicatedHostProfileIdentity{ Name: &profileName, }, Group: &vpcv1.DedicatedHostGroupIdentity{ ID: &groupID, }, }) dedicatedHost, response, err = vpcService.CreateDedicatedHost(options)
DedicatedHostProfileIdentityByName dedicatedHostProfileIdentityModel = new DedicatedHostProfileIdentityByName.Builder() .name(profileName) .build(); DedicatedHostGroupIdentityById dedicatedHostGroupIdentityModel = new DedicatedHostGroupIdentityById.Builder() .id(groupId) .build(); DedicatedHostPrototypeDedicatedHostByGroup dedicatedHostPrototypeModel = new DedicatedHostPrototypeDedicatedHostByGroup.Builder() .name("my-dedicated-host") .profile(dedicatedHostProfileIdentityModel) .group(dedicatedHostGroupIdentityModel) .build(); CreateDedicatedHostOptions createDedicatedHostOptions = new CreateDedicatedHostOptions.Builder() .dedicatedHostPrototype(dedicatedHostPrototypeModel) .build(); Response<DedicatedHost> response = service.createDedicatedHost(createDedicatedHostOptions).execute(); DedicatedHost dedicatedHost = response.getResult();
const params = { dedicatedHostPrototype: { profile: { name: profileName }, group: { id: groupID }, name: 'my-dedicated-host', }, }; const response = await vpcService.createDedicatedHost(params);
dedicated_host_group_identity_model = {} dedicated_host_group_identity_model['id'] = group_id dedicated_host_profile_identity_model = {} dedicated_host_profile_identity_model['name'] = profile dedicated_host_prototype_model = {} dedicated_host_prototype_model[ 'group'] = dedicated_host_group_identity_model dedicated_host_prototype_model[ 'profile'] = dedicated_host_profile_identity_model dedicated_host_prototype = dedicated_host_prototype_model response = service.create_dedicated_host(dedicated_host_prototype)
Response
The amount of memory in gibibytes that is currently available for instances
Possible values: 0 ≤ value ≤ 1024
Example:
128
The available VCPU for the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
available_vcpu
The date and time that the dedicated host was created
The CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
Collection of the dedicated host's disks
The dedicated host group this dedicated host is in
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
group
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
If set to true, instances can be placed on this dedicated host
The instances that are allocated to this dedicated host.
The lifecycle state of the dedicated host.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The total amount of memory in gibibytes for this host
Possible values: 0 ≤ value ≤ 1024
Example:
128
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The dedicated host NUMA configuration
The profile for this dedicated host.
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The globally unique name for this dedicated host profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mx2-host-152x1216
profile
Indicates whether this dedicated host is available for instance creation
The resource group for this dedicated host
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The total number of sockets for this host
Possible values: value ≥ 1
Example:
4
The administrative state of the dedicated host.
The enumerated values for this property may expand in the future.
Possible values: [
available
,degraded
,migrating
,unavailable
]The instance profiles usable by instances placed on this dedicated host.
Possible values: number of items ≥ 1
The total VCPU of the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
vcpu
The zone this dedicated host resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host was created successfully.
An invalid dedicated host prototype object was provided
The dedicated host group family must match the specified host profile family
{ "available_memory": 346, "available_vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "created_at": "2020-05-29T19:38:33Z", "crn": "crn:[...]", "disks": [], "group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_type": "dedicated_host_group" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "instance_placement_enabled": false, "instances": [], "lifecycle_state": "stable", "memory": 346, "name": "test-new", "numa": { "count": 0, "nodes": [] }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/dh2-56x344", "name": "dh2-56x344" }, "provisionable": true, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host", "socket_count": 2, "state": "available", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all disks on a dedicated host
This request lists all 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.
GET /dedicated_hosts/{dedicated_host_id}/disks
Request
Path Parameters
The dedicated host identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id/disks?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listDedicatedHostDisksOptions := vpcService.NewListDedicatedHostDisksOptions( dedicatedHostID, ) dedicatedHostDisksCollection, response, err := vpcService.ListDedicatedHostDisks(listDedicatedHostDisksOptions)
ListDedicatedHostDisksOptions listDedicatedHostDisksOptions = new ListDedicatedHostDisksOptions.Builder() .dedicatedHostId(dedicatedHostId) .build(); Response<DedicatedHostDiskCollection> response = service.listDedicatedHostDisks(listDedicatedHostDisksOptions).execute();
const response = await vpcService.listDedicatedHostDisks({dedicatedHostId})
dedicated_host_disk_collection = vpc_service.list_dedicated_host_disks( dedicated_host_id )
Response
Collection of the dedicated host's disks
Status Code
The dedicated host disks were retrieved successfully.
A dedicated host with the specified identifier could not be found.
{ "disks": [ { "available": 3200, "created_at": "2020-02-28T17:05:47.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/123a490a-9e64-4254-a93b-9a3af3ede270/disks/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "instance_disks": [], "interface_type": "nvme", "name": "my-disk", "provisionable": true, "resource_type": "dedicated_host_disk", "size": 3200, "supported_instance_interface_types": [ "virtio_blk", "nvme" ] }, { "available": 3200, "created_at": "2020-02-28T17:05:48.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/123a490a-9e64-4254-a93b-9a3af3ede270/disks/9b955378-baf7-11ea-a364-000c29475bed", "id": "9b955378-baf7-11ea-a364-000c29475bed", "instance_disks": [], "interface_type": "nvme", "name": "my-disk-2", "provisionable": true, "resource_type": "dedicated_host_disk", "size": 3200, "supported_instance_interface_types": [ "virtio_blk", "nvme" ] } ] }
Retrieve a dedicated host disk
This request retrieves a single dedicated host disk specified by the identifier in the URL.
GET /dedicated_hosts/{dedicated_host_id}/disks/{id}
Request
Path Parameters
The dedicated host identifier
The dedicated host disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getDedicatedHostDiskOptions := vpcService.NewGetDedicatedHostDiskOptions( dedicatedHostID, diskID, ) dedicatedHostDisk, response, err := vpcService.GetDedicatedHostDisk(getDedicatedHostDiskOptions)
GetDedicatedHostDiskOptions getDedicatedHostDiskOptions = new GetDedicatedHostDiskOptions.Builder() .dedicatedHostId(dedicatedHostId) .id(diskId) .build(); Response<DedicatedHostDisk> response = service.getDedicatedHostDisk(getDedicatedHostDiskOptions).execute();
const response = await vpcService.getDedicatedHostDisk({dedicatedHostId, id})
dedicated_host_disk = vpc_service.get_dedicated_host_disk( dedicated_host_id, id )
Response
The remaining space left for instance placement in GB (gigabytes)
The date and time that the disk was created
The URL for this disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
Instance disks that are on this dedicated host disk
The disk interface used for attaching the disk
The enumerated values for this property may expand in the future.
Possible values: [
nvme
]The name for this dedicated host disk. The name is unique across all disks on the dedicated host.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dedicated-host-disk
Indicates whether this dedicated host disk is available for instance disk creation
The resource type
Possible values: [
dedicated_host_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
The instance disk interfaces supported for this dedicated host disk.
Possible values: [
nvme
,virtio_blk
]Possible values: number of items ≥ 1, contains only unique items
The lifecycle state of this dedicated host disk
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
Status Code
The dedicated host disk was retrieved successfully.
A dedicated host disk with the specified identifier could not be found for the specified dedicated host.
{ "available": 3200, "created_at": "2020-02-28T17:05:47.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/123a490a-9e64-4254-a93b-9a3af3ede270/disks/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "instance_disks": [], "interface_type": "nvme", "name": "my-disk", "provisionable": true, "resource_type": "dedicated_host_disk", "size": 3200, "supported_instance_interface_types": [ "virtio_blk", "nvme" ] }
Update a dedicated host disk
This request updates the dedicated host disk with the information in a provided patch.
PATCH /dedicated_hosts/{dedicated_host_id}/disks/{id}
Request
Path Parameters
The dedicated host identifier
The dedicated host disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The dedicated host disk patch
The name for this dedicated host disk. The name must not be used by another disk on the dedicated host.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-disk-updated
curl -X PATCH "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-disk-updated" }'
dedicatedHostDiskPatchModel := &vpcv1.DedicatedHostDiskPatch{ Name: &name, } dedicatedHostDiskPatchModelAsPatch, asPatchErr := dedicatedHostDiskPatchModel.AsPatch() updateDedicatedHostDiskOptions := vpcService.NewUpdateDedicatedHostDiskOptions( dedicatedHostID, diskID, dedicatedHostDiskPatchModelAsPatch, )
DedicatedHostDiskPatch dedicatedHostDiskPatchModel = new DedicatedHostDiskPatch.Builder() .name("my-disk-update") .build(); Map<String, Object> dedicatedHostDiskPatchModelAsPatch = dedicatedHostDiskPatchModel.asPatch(); UpdateDedicatedHostDiskOptions updateDedicatedHostDiskOptions = new UpdateDedicatedHostDiskOptions.Builder() .dedicatedHostId(dedicatedHostId) .id(diskId) .dedicatedHostDiskPatch(dedicatedHostDiskPatchModelAsPatch) .build();
const response = await vpcService.updateDedicatedHostDisk({ dedicatedHostId, id, name, })
dedicated_host_disk_patch_model = { name='my-disk-updated' } dedicated_host_disk = vpc_service.update_dedicated_host_disk( dedicated_host_id, id, dedicated_host_disk_patch=dedicated_host_disk_patch_model )
Response
The remaining space left for instance placement in GB (gigabytes)
The date and time that the disk was created
The URL for this disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
Instance disks that are on this dedicated host disk
The disk interface used for attaching the disk
The enumerated values for this property may expand in the future.
Possible values: [
nvme
]The name for this dedicated host disk. The name is unique across all disks on the dedicated host.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-dedicated-host-disk
Indicates whether this dedicated host disk is available for instance disk creation
The resource type
Possible values: [
dedicated_host_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
The instance disk interfaces supported for this dedicated host disk.
Possible values: [
nvme
,virtio_blk
]Possible values: number of items ≥ 1, contains only unique items
The lifecycle state of this dedicated host disk
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
Status Code
The dedicated host disk was updated successfully.
An invalid dedicated host disk patch was provided.
A dedicated host disk with the specified identifier could not be found for the specified dedicated host.
{ "available": 3200, "created_at": "2020-02-28T17:05:47.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/123a490a-9e64-4254-a93b-9a3af3ede270/disks/35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "instance_disks": [], "interface_type": "nvme", "name": "my-disk-updated", "provisionable": true, "resource_type": "dedicated_host_disk", "size": 3200, "supported_instance_interface_types": [ "virtio_blk", "nvme" ] }
Request
Path Parameters
The dedicated host identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteDedicatedHostOptions(id) response, err := vpcService.DeleteDedicatedHost(options)
DeleteDedicatedHostOptions deleteDedicatedHostOptions = new DeleteDedicatedHostOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteDedicatedHost(deleteDedicatedHostOptions).execute();
const response = await vpcService.deleteDedicatedHost({ id });
response = service.delete_dedicated_host(id)
Retrieve a dedicated host
This request retrieves a single dedicated host specified by the identifiers in the URL.
GET /dedicated_hosts/{id}
Request
Path Parameters
The dedicated host identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetDedicatedHostOptions(id) dedicatedHost, response, err := vpcService.GetDedicatedHost(options)
GetDedicatedHostOptions getDedicatedHostOptions = new GetDedicatedHostOptions.Builder() .id(id) .build(); Response<DedicatedHost> response = service.getDedicatedHost(getDedicatedHostOptions).execute(); DedicatedHost dedicatedHost = response.getResult();
const response = await vpcService.getDedicatedHost({ id });
response = service.get_dedicated_host(id) if response.status_code == 200: dedicated_host = response.get_result()
Response
The amount of memory in gibibytes that is currently available for instances
Possible values: 0 ≤ value ≤ 1024
Example:
128
The available VCPU for the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
available_vcpu
The date and time that the dedicated host was created
The CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
Collection of the dedicated host's disks
The dedicated host group this dedicated host is in
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
group
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
If set to true, instances can be placed on this dedicated host
The instances that are allocated to this dedicated host.
The lifecycle state of the dedicated host.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The total amount of memory in gibibytes for this host
Possible values: 0 ≤ value ≤ 1024
Example:
128
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The dedicated host NUMA configuration
The profile for this dedicated host.
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The globally unique name for this dedicated host profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mx2-host-152x1216
profile
Indicates whether this dedicated host is available for instance creation
The resource group for this dedicated host
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The total number of sockets for this host
Possible values: value ≥ 1
Example:
4
The administrative state of the dedicated host.
The enumerated values for this property may expand in the future.
Possible values: [
available
,degraded
,migrating
,unavailable
]The instance profiles usable by instances placed on this dedicated host.
Possible values: number of items ≥ 1
The total VCPU of the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
vcpu
The zone this dedicated host resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host was retrieved successfully.
A dedicated host with the specified dedicated host and group identifiers could not be found.
{ "available_memory": 346, "available_vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "created_at": "2020-05-29T19:38:33Z", "crn": "crn:[...]", "disks": [], "group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_type": "dedicated_host_group" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "instance_placement_enabled": false, "instances": [], "lifecycle_state": "stable", "memory": 346, "name": "test-new", "numa": { "count": 0, "nodes": [] }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/dh2-56x344", "name": "dh2-56x344" }, "provisionable": true, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host", "socket_count": 2, "state": "available", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a dedicated host
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.
PATCH /dedicated_hosts/{id}
Request
Path Parameters
The dedicated host identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The dedicated host patch
If set to true, instances can be placed on this dedicated host
The name for this dedicated host. The name must not be used by another dedicated host in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-host
curl -X PATCH "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-host" }'
options := &vpcv1.UpdateDedicatedHostOptions{ DedicatedHostID: &id, Name: &name, } dedicatedHost, response, err := vpcService.UpdateDedicatedHost(options)
UpdateDedicatedHostOptions updateDedicatedHostOptions = new UpdateDedicatedHostOptions.Builder() .id(id) .name("my-dedicated-host-update") .build(); Response<DedicatedHost> response = service.updateDedicatedHost(updateDedicatedHostOptions).execute(); DedicatedHost dedicatedHost = response.getResult();
const response = await vpcService.updateDedicatedHost({ id, name: 'my-dedicated-host', });
new_name = 'my-dedicated-host-updated' response = service.update_dedicated_host(id, name=new_name)
Response
The amount of memory in gibibytes that is currently available for instances
Possible values: 0 ≤ value ≤ 1024
Example:
128
The available VCPU for the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
available_vcpu
The date and time that the dedicated host was created
The CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
Collection of the dedicated host's disks
The dedicated host group this dedicated host is in
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The URL for this dedicated host group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
group
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
If set to true, instances can be placed on this dedicated host
The instances that are allocated to this dedicated host.
The lifecycle state of the dedicated host.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The total amount of memory in gibibytes for this host
Possible values: 0 ≤ value ≤ 1024
Example:
128
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The dedicated host NUMA configuration
The profile for this dedicated host.
The URL for this dedicated host
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The globally unique name for this dedicated host profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
mx2-host-152x1216
profile
Indicates whether this dedicated host is available for instance creation
The resource group for this dedicated host
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The total number of sockets for this host
Possible values: value ≥ 1
Example:
4
The administrative state of the dedicated host.
The enumerated values for this property may expand in the future.
Possible values: [
available
,degraded
,migrating
,unavailable
]The instance profiles usable by instances placed on this dedicated host.
Possible values: number of items ≥ 1
The total VCPU of the dedicated host
The VCPU architecture
Example:
amd64
The number of VCPUs assigned
Possible values: value ≥ 1
Example:
4
The VCPU manufacturer
Example:
intel
vcpu
The zone this dedicated host resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The dedicated host was updated successfully.
An invalid dedicated host patch was provided.
A dedicated host with the specified dedicated host group and dedicated host identifiers could not be found.
{ "available_memory": 346, "available_vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "created_at": "2020-05-29T19:38:33Z", "crn": "crn:[...]", "disks": [], "group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/groups/0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "id": "0787-b93509fb-78f3-453b-a104-75ab67a2e72e", "name": "bagpipe-unwelcome-viselike-cramp-rendition-skincare", "resource_type": "dedicated_host_group" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_hosts/0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221", "instance_placement_enabled": false, "instances": [], "lifecycle_state": "stable", "memory": 346, "name": "my-host", "numa": { "count": 0, "nodes": [] }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/dedicated_host/profiles/dh2-56x344", "name": "dh2-56x344" }, "provisionable": true, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "dedicated_host", "socket_count": 2, "state": "available", "supported_instance_profiles": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-2x16", "name": "mx2-2x16", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-4x32", "name": "mx2-4x32", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-8x64", "name": "mx2-8x64", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-16x128", "name": "mx2-16x128", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-32x256", "name": "mx2-32x256", "resource_type": "instance_profile" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/mx2-48x384", "name": "mx2-48x384", "resource_type": "instance_profile" } ], "vcpu": { "architecture": "amd64", "count": 56, "manufacturer": "intel" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all placement groups
This request lists all placement groups in the region.
GET /placement_groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/placement_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListPlacementGroupsOptions{} placementGroups, response, err := vpcService.ListPlacementGroups(options)
ListPlacementGroupsOptions listPlacementGroupsOptions = new ListPlacementGroupsOptions.Builder() .build(); Response<PlacementGroupCollection> response = service.listPlacementGroups(listPlacementGroupsOptions).execute();
const res = await vpcService.listPlacementGroups();
response = service.list_placement_groups()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/placement_groups?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of placement groups
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/placement_groups?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The placement groups were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/placement_groups?limit=50" }, "limit": 50, "placement_groups": [ { "created_at": "2020-12-29T19:55:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-updated-placement-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" } ], "total_count": 1 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The placement group prototype object
The strategy for this placement group:
host_spread
: place on different compute hostspower_spread
: place on compute hosts that use different power sources
The enumerated values for this property may expand in the future.
Allowable values: [
host_spread
,power_spread
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The name for this placement group. The name must not be used by another placement group in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/placement_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-placement-group", "strategy": "host_spread" }'
name := "my-placement-group" strategy := "host_spread" options := &vpcv1.CreatePlacementGroupOptions{ Strategy: &strategy, Name: &name, } placementGroup, response, err := vpcService.CreatePlacementGroup(options)
CreatePlacementGroupOptions createPlacementGroupOptions = new CreatePlacementGroupOptions.Builder() .strategy("host_spread") .name("my-placement-group") .build(); Response<PlacementGroup> response = service.createPlacementGroup(createPlacementGroupOptions).execute();
const params = { strategy: 'host_spread', name: 'my-placement-group', }; const res = await vpcService.createPlacementGroup(params);
response = service.create_placement_group( strategy='host_spread', name='my-placement-group', )
Response
The date and time that the placement group was created
The CRN for this placement group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The URL for this placement group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The unique identifier for this placement group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The lifecycle state of the placement group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this placement group. The name is unique across all placement groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
The resource group for this placement group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
placement_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The strategy for this placement group:
host_spread
: place on different compute hostspower_spread
: place on compute hosts that use different power sources
The enumerated values for this property may expand in the future.
Possible values: [
host_spread
,power_spread
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The placement group was created successfully.
An invalid placement group prototype object was provided.
{ "created_at": "2020-12-29T19:55:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-placement-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" }
Delete a placement group
This request deletes a placement group. This operation cannot be reversed. For this request to succeed, the placement group must not be associated with an instance.
DELETE /placement_groups/{id}
Request
Path Parameters
The placement group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/placement_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deletePlacementGroupOptions := &vpcv1.DeletePlacementGroupOptions{ ID: &placementGroupID, } response, err := vpcService.DeletePlacementGroup(deletePlacementGroupOptions)
DeletePlacementGroupOptions deletePlacementGroupOptions = new DeletePlacementGroupOptions.Builder() .id(placementGroupID) .build(); Response<Void> response = service.deletePlacementGroup(deletePlacementGroupOptions).execute();
const params = { id: placementGroupID, }; const res = await vpcService.deletePlacementGroup(params);
response = service.delete_placement_group(placementGroupID)
Retrieve a placement group
This request retrieves a single placement group specified by identifier in the URL.
GET /placement_groups/{id}
Request
Path Parameters
The placement group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/placement_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetPlacementGroupOptions{ ID: &placementGroupID, } placementGroup, response, err := vpcService.GetPlacementGroup(options)
GetPlacementGroupOptions getPlacementGroupOptions = new GetPlacementGroupOptions.Builder() .id(placementGroupID) .build(); Response<PlacementGroup> response = service.getPlacementGroup(getPlacementGroupOptions).execute();
const params = { id: placementGroupID, }; const res = await vpcService.getPlacementGroup(params);
response = service.get_placement_group(placementGroupID)
Response
The date and time that the placement group was created
The CRN for this placement group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The URL for this placement group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The unique identifier for this placement group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The lifecycle state of the placement group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this placement group. The name is unique across all placement groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
The resource group for this placement group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
placement_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The strategy for this placement group:
host_spread
: place on different compute hostspower_spread
: place on compute hosts that use different power sources
The enumerated values for this property may expand in the future.
Possible values: [
host_spread
,power_spread
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The placement group was retrieved successfully.
A placement group with the specified identifier could not be found.
{ "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-placement-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" }
Update a placement group
This request updates a placement group with the information provided placement group patch. The placement group patch object is structured in the same way as a retrieved placement group and contains only the information to be updated.
PATCH /placement_groups/{id}
Request
Path Parameters
The placement group identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The placement group patch
The name for this placement group. The name must not be used by another placement group in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
curl -X PATCH "$vpc_api_endpoint/v1/placement_groups/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-placement-group-updated" }'
name := "my-placement-group-updated" placementGroupPatchModel := &vpcv1.PlacementGroupPatch{ Name: &name, } placementGroupPatchModelAsPatch, _ := placementGroupPatchModel.AsPatch() options := &vpcv1.UpdatePlacementGroupOptions{ ID: &placementGroupID, PlacementGroupPatch: placementGroupPatchModelAsPatch, } placementGroup, response, err := vpcService.UpdatePlacementGroup(options)
PlacementGroupPatch placementGroupPatchModel = new PlacementGroupPatch.Builder() .name("my-placement-group-updated") .build(); Map<String, Object> placementGroupPatchModelAsPatch = placementGroupPatchModel.asPatch(); UpdatePlacementGroupOptions updatePlacementGroupOptions = new UpdatePlacementGroupOptions.Builder() .id(placementGroupID) .placementGroupPatch(placementGroupPatchModelAsPatch) .build(); Response<PlacementGroup> response = service.updatePlacementGroup(updatePlacementGroupOptions).execute();
const params = { id: placementGroupID, name: 'my-placement-group-updated', }; const res = await vpcService.updatePlacementGroup(params);
placement_group_patch_model = {} placement_group_patch_model['name'] = 'my-placement-group-updated' response = service.update_placement_group( placementGroupID, placement_group_patch=placement_group_patch_model )
Response
The date and time that the placement group was created
The CRN for this placement group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The URL for this placement group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The unique identifier for this placement group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r018-418fe842-a3e9-47b9-a938-1aa5bd632871
The lifecycle state of the placement group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this placement group. The name is unique across all placement groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
The resource group for this placement group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
placement_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The strategy for this placement group:
host_spread
: place on different compute hostspower_spread
: place on compute hosts that use different power sources
The enumerated values for this property may expand in the future.
Possible values: [
host_spread
,power_spread
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The placement group was updated successfully.
An invalid placement group patch was provided.
A placement group with the specified identifier could not be found.
{ "created_at": "2020-12-29T19:55:00Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/placement_groups/r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-updated-placement-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" }
List all bare metal server profiles
This request lists all 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.
GET /bare_metal_server/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/bare_metal_server/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListBareMetalServerProfilesOptions() bareMetalServerProfileCollection, response, err := vpcService.ListBareMetalServerProfiles(options)
ListBareMetalServerProfilesOptions listBareMetalServerProfilesOptions = new ListBareMetalServerProfilesOptions.Builder() .build(); Response<BareMetalServerProfileCollection> response = vpcService.listBareMetalServerProfiles(listBareMetalServerProfilesOptions).execute(); BareMetalServerProfileCollection bareMetalServerProfileCollection = response.getResult();
const response = await vpcService.listBareMetalServerProfiles()
bare_metal_server_profile_collection = service.list_bare_metal_server_profiles() .get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of bare metal server profiles
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The bare metal server profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768?limit=50" }, "limit": 50, "profiles": [ { "bandwidth": { "type": "fixed", "value": 100000 }, "console_types": { "type": "enum", "values": [ "serial", "vnc" ] }, "cpu_architecture": { "type": "fixed", "value": "amd64" }, "cpu_core_count": { "type": "fixed", "value": 96 }, "cpu_socket_count": { "type": "fixed", "value": 4 }, "disks": [ { "quantity": { "type": "fixed", "value": 1 }, "size": { "type": "fixed", "value": 960 }, "supported_interface_types": { "default": "sata", "type": "enum", "values": [ "sata" ] } }, { "quantity": { "type": "fixed", "value": 16 }, "size": { "type": "fixed", "value": 3200 }, "supported_interface_types": { "default": "nvme", "type": "enum", "values": [ "nvme" ] } } ], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768", "memory": { "type": "fixed", "value": 768 }, "name": "bx2d-metal-192x768", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 128, "min": 1, "type": "range" }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "resource_type": "bare_metal_server_profile", "supported_trusted_platform_module_modes": { "type": "enum", "values": [ "tpm_2" ] }, "virtual_network_interfaces_supported": { "type": "fixed", "value": true } }, { "bandwidth": { "type": "fixed", "value": 100000 }, "console_types": { "type": "enum", "values": [ "serial", "vnc" ] }, "cpu_architecture": { "type": "fixed", "value": "amd64" }, "cpu_core_count": { "type": "fixed", "value": 96 }, "cpu_socket_count": { "type": "fixed", "value": 4 }, "disks": [ { "quantity": { "type": "fixed", "value": 1 }, "size": { "type": "fixed", "value": 960 }, "supported_interface_types": { "default": "sata", "type": "enum", "values": [ "sata" ] } } ], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2-metal-192x768", "memory": { "type": "fixed", "value": 768 }, "name": "bx2-metal-192x768", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 128, "min": 1, "type": "range" }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "resource_type": "bare_metal_server_profile", "supported_trusted_platform_module_modes": { "type": "enum", "values": [ "disabled" ] }, "virtual_network_interfaces_supported": { "type": "fixed", "value": true } } ], "total_count": 2 }
Retrieve a bare metal server profile
This request retrieves a single bare metal server profile specified by the name in the URL.
GET /bare_metal_server/profiles/{name}
Request
Path Parameters
The bare metal server profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_server/profiles/$profile_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerProfileOptions{ Name: &bareMetalServerProfileName, } bareMetalServerProfile, response, err := vpcService.GetBareMetalServerProfile(options)
GetBareMetalServerProfileOptions getBareMetalServerProfileOptions = new GetBareMetalServerProfileOptions.Builder() .name(bareMetalServerProfileName) .build(); Response<BareMetalServerProfile> response = vpcService.getBareMetalServerProfile(getBareMetalServerProfileOptions).execute(); BareMetalServerProfile bareMetalServerProfile = response.getResult();
const params = { name: bareMetalServerProfileName, }; const response = await vpcService.getBareMetalServerProfile(params)
bare_metal_server_profile = service.get_bare_metal_server_profile( name=bareMetalServerProfileName).get_result()
Response
The console type configuration for a bare metal server with this profile.
Collection of the bare metal server profile's disks
Possible values: number of items ≥ 0
The product family this bare metal server profile belongs to
Example:
balanced
The URL for this bare metal server profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles/bx2-metal-192x768
The name for this bare metal server profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-metal-192x768
The resource type
Possible values: [
bare_metal_server_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The supported trusted platform module modes for this bare metal server profile.
Indicates whether this profile supports virtual network interfaces
Examples:View
Status Code
The bare metal server profile was retrieved successfully
A bare metal server profile with the specified name could not be found.
{ "bandwidth": { "type": "fixed", "value": 100000 }, "console_types": { "type": "enum", "values": [ "serial", "vnc" ] }, "cpu_architecture": { "type": "fixed", "value": "amd64" }, "cpu_core_count": { "type": "fixed", "value": 96 }, "cpu_socket_count": { "type": "fixed", "value": 4 }, "disks": [ { "quantity": { "type": "fixed", "value": 1 }, "size": { "type": "fixed", "value": 960 }, "supported_interface_types": { "default": "sata", "type": "enum", "values": [ "sata" ] } } ], "family": "balanced", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2-metal-192x768", "memory": { "type": "fixed", "value": 768 }, "name": "bx2-metal-192x768", "network_attachment_count": { "max": 128, "min": 1, "type": "range" }, "network_interface_count": { "max": 128, "min": 1, "type": "range" }, "os_architecture": { "default": "amd64", "type": "enum", "values": [ "amd64" ] }, "resource_type": "bare_metal_server_profile", "supported_trusted_platform_module_modes": { "type": "enum", "values": [ "disabled" ] }, "virtual_network_interfaces_supported": { "type": "fixed", "value": true } }
List all bare metal servers
This request lists all bare metal servers in the region.
GET /bare_metal_servers
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServersOptions{} bareMetalServerCollection, response, err := vpcService.ListBareMetalServers(options)
ListBareMetalServersOptions listBareMetalServersOptions = new ListBareMetalServersOptions.Builder() .build(); Response<BareMetalServerCollection> response = vpcService.listBareMetalServers(listBareMetalServersOptions).execute(); BareMetalServerCollection bareMetalServerCollection = response.getResult();
const response = await vpcService.listBareMetalServers()
bare_metal_server_collection = service.list_bare_metal_servers().get_result()
Response
Collection of bare metal servers
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The bare metal servers were retrieved successfully.
{ "bare_metal_servers": [ { "bandwidth": 100000, "boot_target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk" }, "cpu": { "architecture": "amd64", "core_count": 96, "socket_count": 4, "threads_per_core": 2 }, "created_at": "2021-05-21T06:09:15.000Z", "crn": "crn:[...]", "disks": [ { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk", "size": 960 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-86003aba-47db-4d07-bd76-62e00cca83e5", "id": "2302-86003aba-47db-4d07-bd76-62e00cca83e5", "interface_type": "nvme", "name": "elderly-mountain-trout-opponent", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "id": "2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "interface_type": "nvme", "name": "could-kilt-twisty-unloaded", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-e544d72d-ca08-4924-b748-a8f67b66286d", "id": "2302-e544d72d-ca08-4924-b748-a8f67b66286d", "interface_type": "nvme", "name": "wildcat-impromptu-dribble-hesitate", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "id": "2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "interface_type": "nvme", "name": "imperfect-stimulate-culpable-thumb", "resource_type": "bare_metal_server_disk", "size": 3200 } ], "enable_secure_boot": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "id": "2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 768, "name": "my-bare-metal-server", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "id": "2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.12", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/a053a8c6-ed22-4773-8120-4c0c67c8b64a", "id": "a053a8c6-ed22-4773-8120-4c0c67c8b64a", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "id": "2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.9", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768", "name": "bx2d-metal-192x768", "resource_type": "bare_metal_server_profile" }, "resource_group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "resource_type": "bare_metal_server", "status": "running", "status_reasons": [], "trusted_platform_module": { "enabled": false, "mode": "disabled", "supported_modes": [ "disabled", "tpm_2" ] }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "id": "r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers?limit=50" }, "limit": 50, "total_count": 1 }
Create a bare metal server
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.
POST /bare_metal_servers
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.create
Generated for each virtual network interface created
is.virtual-network-interface.virtual-network-interface.attach
Generated for:
- each virtual network interface being attached to a bare metal server network attachment
- each virtual network interface for each reserved IP being attached to it
- each virtual network interface for each security group being attached to it
is.bare-metal-server.network-attachment.attach
Generated for each virtual network interface being attached to a bare metal server network attachment
is.bare-metal-server.bare-metal-server.create
is.bare-metal-server.network-attachment.create
Generated for each bare metal server network attachment created
is.bare-metal-server.network-interface.create
Generated for each bare metal server network interface created
is.bare-metal-server.network-interface.attach
Generated for each resource being attached to a bare metal server network interface:
- reserved IPs
- security groups
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to:
- a bare metal server network interface, or
- a virtual network interface
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.security-group.security-group.attach
Generated for each security group being attached to:
- a bare metal server network interface, or
- a new virtual network interface
is.subnet.subnet.update
Generated for each reserved IP created
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server prototype object
The profile to use for this bare metal server
The name for this bare metal server profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-metal-192x768
profile
The zone this bare metal server will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.
Default:
false
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server
The resource group to use. If unspecified, the account's default resource group will be used.
The VPC this bare metal server will reside in.
If specified, it must match the VPC for the subnets that the network attachments or network interfaces of the bare metal server are attached to.
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The primary network attachment to create for the bare metal server
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
ofs390x
- Has an
Allowable values: [
pci
]Default:
pci
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
primary_network_attachment
The additional network attachments to create for the bare metal server.
Possible values: number of items ≥ 0, contains only unique items
One of
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "initialization": { "image": { "id":"r134-31c8ca90-2623-48d7-8cf7-737be6fc4c3e" }, "keys": [ { "id":"r134-fa0d609a-ced3-45d7-b3e9-e53268e47289" } ] }, "primary_network_interface": { "interface_type": "pci", "name": "my-primary-network-interface", "subnet": { "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5" }, "allowed_vlans": [ 4 ] }, "network_interfaces": [ { "interface_type": "vlan", "name": "my-vlan-interface", "allow_interface_to_float": true, "subnet": { "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5" }, "vlan": 4 } ], "name": "my-bare-metal-server", "profile": { "name": "bx2d-metal-192x768" }, "zone": { "name": "us-south-3" } }'
imageIdentityModel := &vpcv1.ImageIdentityByID{ ID: &imageID, } keyIdentityModel := &vpcv1.KeyIdentityByID{ ID: &keyID, } bareMetalServerInitializationPrototypeModel := &vpcv1.BareMetalServerInitializationPrototype{ Image: imageIdentityModel, Keys: []vpcv1.KeyIdentityIntf{keyIdentityModel}, } subnetIdentityModel := &vpcv1.SubnetIdentityByID{ ID: &subnetId, } bareMetalServerPrimaryNetworkInterfacePrototypeModel := &vpcv1.BareMetalServerPrimaryNetworkInterfacePrototype{ Subnet: subnetIdentityModel, } bareMetalServerProfileIdentityModel := &vpcv1.BareMetalServerProfileIdentityByName{ Name: &bareMetalServerProfileName, } zoneIdentityModel := &vpcv1.ZoneIdentityByName{ Name: &zoneName, } options := &vpcv1.CreateBareMetalServerOptions{ Initialization: bareMetalServerInitializationPrototypeModel, PrimaryNetworkInterface: bareMetalServerPrimaryNetworkInterfacePrototypeModel, Profile: bareMetalServerProfileIdentityModel, Zone: zoneIdentityModel, Name: &[]string{"my-bare-metal-server"}[0], } bareMetalServer, response, err := vpcService.CreateBareMetalServer(options)
ImageIdentityById imageIdentityModel = new ImageIdentityById.Builder() .id(imageId) .build(); KeyIdentityById keyIdentityModel = new KeyIdentityById.Builder() .id(keyId) .build(); BareMetalServerInitializationPrototype bareMetalServerInitializationPrototypeModel = new BareMetalServerInitializationPrototype.Builder() .image(imageIdentityModel) .keys(new java.util.ArrayList<KeyIdentity>(java.util.Arrays.asList(keyIdentityModel))) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); Long[] allowedVlans = {4L}; BareMetalServerPrimaryNetworkInterfacePrototype bareMetalServerPrimaryNetworkInterfacePrototypeModel = new BareMetalServerPrimaryNetworkInterfacePrototype.Builder() .interfaceType("pci") .allowedVlans(new java.util.ArrayList<Long>(java.util.Arrays.asList(allowedVlans))) .enableInfrastructureNat(true) .name("my-network-interface") .subnet(subnetIdentityModel) .build(); BareMetalServerProfileIdentityByName bareMetalServerProfileIdentityModel = new BareMetalServerProfileIdentityByName.Builder() .name(bareMetalServerProfileName) .build(); VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreateBareMetalServerOptions createBareMetalServerOptions = new CreateBareMetalServerOptions.Builder() .initialization(bareMetalServerInitializationPrototypeModel) .primaryNetworkInterface(bareMetalServerPrimaryNetworkInterfacePrototypeModel) .profile(bareMetalServerProfileIdentityModel) .name("my-bare-metal-server") .vpc(vpcIdentityModel) .zone(zoneIdentityModel) .build(); Response<BareMetalServer> response = vpcService.createBareMetalServer(createBareMetalServerOptions).execute(); BareMetalServer bareMetalServer = response.getResult();
const imageIdentityModel = { id: imageId, }; const keyIdentityModel = { id: keyId, }; const bareMetalServerInitializationPrototypeModel = { image: imageIdentityModel, keys: [keyIdentityModel], user_data: userData, }; const subnetIdentityModel = { id: subnetId, }; const bareMetalServerPrimaryNetworkInterfacePrototypeModel = { allow_ip_spoofing: true, allowed_vlans: [4], enable_infrastructure_nat: true, interface_type: 'pci', name: 'my-network-interface', subnet: subnetIdentityModel, }; const bareMetalServerProfileIdentityModel = { name: bareMetalServerProfileName, }; const zoneIdentityModel = { name: zone, }; const vpcIdentityModel = { id: vpcId, }; const params = { initialization: bareMetalServerInitializationPrototypeModel, primaryNetworkInterface: bareMetalServerPrimaryNetworkInterfacePrototypeModel, profile: bareMetalServerProfileIdentityModel, zone: zoneIdentityModel, name: 'my-bare-metal-server', vpc: vpcIdentityModel, }; const response = await vpcService.createBareMetalServer(params);
image_identity_model = { 'id': imageId, } key_identity_model = { 'id': keyId, } bare_metal_server_initialization_prototype_model = { 'image': image_identity_model, 'keys': [key_identity_model], } bare_metal_server_primary_network_interface_prototype_model = { 'subnet': { 'id': subnetId, }, } zone_identity_model = { 'name': zone, } bare_metal_server = service.create_bare_metal_server( initialization=bare_metal_server_initialization_prototype_model, primary_network_interface= bare_metal_server_primary_network_interface_prototype_model, profile={ 'name': bareMetalServerProfileName }, name='my-bare-metal-server', zone=zone_identity_model).get_result()
Response
The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces
Possible values: 1 ≤ value ≤ 1000000
Example:
20000
The resource from which this bare metal server is booted.
The resources supported by this property may expand in the future.
Examples:ViewThe bare metal server CPU configuration
The date and time that the bare metal server was created
The CRN for this bare metal server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::bare-metal-server:1e09281b-f177-46fb-baf1-bc152b2e391a
The disks for this bare metal server, including any disks that are associated with the
boot_target
.Possible values: number of items ≥ 0
Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.
The URL for this bare metal server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this bare metal server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the bare metal server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 100000
Example:
1536
The name for this bare metal server. The name is unique across all bare metal servers in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server
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.
Possible values: number of items ≥ 1
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this bare metal server network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this bare metal server
The URL for this bare metal server profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles/bx2-metal-192x768
The name for this bare metal server profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-metal-192x768
The resource type
Possible values: [
bare_metal_server_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this bare metal server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
bare_metal_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this bare metal server:
deleting
: server is undergoing deletionfailed
: server is failed and not usable (seestatus_reasons
)maintenance
: server is undergoing maintenance (not usable)pending
: server is being provisioned and not yet usablerestarting
: server is restarting and not yet usablerunning
: server is powered onstarting
: server is starting and not yet usablestopped
: server is powered off
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,maintenance
,pending
,restarting
,running
,starting
,stopped
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The VPC this bare metal server resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this bare metal server resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The network attachments for this bare metal server, including the primary network attachment.
Possible values: number of items ≥ 0
The primary network attachment for this bare metal server.
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
Status Code
The bare metal server was created successfully.
An invalid bare metal server prototype object was provided.
{ "bandwidth": 100000, "boot_target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk" }, "cpu": { "architecture": "amd64", "core_count": 96, "socket_count": 4, "threads_per_core": 2 }, "created_at": "2021-05-21T06:09:15.000Z", "crn": "crn:[...]", "disks": [ { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk", "size": 960 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-86003aba-47db-4d07-bd76-62e00cca83e5", "id": "2302-86003aba-47db-4d07-bd76-62e00cca83e5", "interface_type": "nvme", "name": "elderly-mountain-trout-opponent", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "id": "2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "interface_type": "nvme", "name": "could-kilt-twisty-unloaded", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-e544d72d-ca08-4924-b748-a8f67b66286d", "id": "2302-e544d72d-ca08-4924-b748-a8f67b66286d", "interface_type": "nvme", "name": "wildcat-impromptu-dribble-hesitate", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "id": "2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "interface_type": "nvme", "name": "imperfect-stimulate-culpable-thumb", "resource_type": "bare_metal_server_disk", "size": 3200 } ], "enable_secure_boot": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "id": "2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 768, "name": "my-bare-metal-server", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "id": "2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.12", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/a053a8c6-ed22-4773-8120-4c0c67c8b64a", "id": "a053a8c6-ed22-4773-8120-4c0c67c8b64a", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "id": "2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.9", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768", "name": "bx2d-metal-192x768", "resource_type": "bare_metal_server_profile" }, "resource_group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "resource_type": "bare_metal_server", "status": "pending", "status_reasons": [], "trusted_platform_module": { "enabled": false, "mode": "disabled", "supported_modes": [ "disabled", "tpm_2" ] }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "id": "r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } }
Retrieve the console WebSocket for a bare metal server
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.
GET /bare_metal_servers/{bare_metal_server_id}/console
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A URL safe single-use token used to access the console WebSocket.
Example:
VGhpcyBJcyBhIHRva2Vu
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/console?version=2024-04-30&generation=2&maturity=beta&access_token=VGhpcyBJcyBhIHRva2Vu"
const params = { bareMetalServerId: bareMetalServerId, accessToken: 'VGhpcyBJcyBhIHRva2Vu', }; const response = await vpcService.getBareMetalServerConsole(params)
Response
Status Code
A WebSocket connection was established.
The open console limit for bare metal servers was reached.
An invalid bare metal server console access token was provided.
A bare metal server with the specified identifier could not be found.
The WebSocket protocol is required.
No Sample Response
Create a console access token for a bare metal server
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.
POST /bare_metal_servers/{bare_metal_server_id}/console_access_token
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server console access token prototype
The bare metal server console type for which this token may be used
Must be
serial
for bare metal servers with acpu.architecture
ofs390x
Allowable values: [
serial
,vnc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
serial
Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.
Default:
false
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/console_access_token?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "console_type": "vnc" }'
options := &vpcv1.CreateBareMetalServerConsoleAccessTokenOptions{ BareMetalServerID: &bareMetalServerId, } options.SetConsoleType("serial") bareMetalServerConsoleAccessToken, response, err := vpcService.CreateBareMetalServerConsoleAccessToken(options)
CreateBareMetalServerConsoleAccessTokenOptions createBareMetalServerConsoleAccessTokenOptions = new CreateBareMetalServerConsoleAccessTokenOptions.Builder() .bareMetalServerId(bareMetalServerId) .consoleType("serial") .build(); Response<BareMetalServerConsoleAccessToken> response = vpcService.createBareMetalServerConsoleAccessToken(createBareMetalServerConsoleAccessTokenOptions).execute(); BareMetalServerConsoleAccessToken bareMetalServerConsoleAccessToken = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, consoleType: 'serial', }; const response = await vpcService.createBareMetalServerConsoleAccessToken(params)
bare_metal_server_console_access_token = service.create_bare_metal_server_console_access_token( bare_metal_server_id=bare_metal_server_id, console_type='serial').get_result()
Response
The bare metal server console access token information
A URL safe single-use token used to access the console WebSocket.
Example:
VGhpcyBJcyBhIHRva2Vu
The bare metal server console type for which this token may be used
Possible values: [
serial
,vnc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
serial
The date and time that the access token was created
Example:
2020-07-27T21:50:14.000Z
The date and time that the access token will expire
Example:
2020-07-27T21:51:14.000Z
Indicates whether to disconnect an existing serial console session as the serial console cannot be shared. This has no effect on VNC consoles.
The URL to access this bare metal server console.
Example:
wss://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/console?access_token=VGhpcyBJcyBhIHRva2Vu
Status Code
The access token was created successfully.
An invalid bare metal server console access token prototype object was provided.
The bare metal server console access token is not allowed to be created.
A bare metal server with the specified identifier could not be found.
{ "access_token": "VGhpcyBJcyBhIHRva2Vu", "console_type": "vnc", "created_at": "2021-05-21T06:39:04.000Z", "expires_at": "2021-05-21T06:42:04.000Z", "force": false, "href": "wss://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/console?access_token=VGhpcyBJcyBhIHRva2Vu&version=2024-04-30&generation=2&maturity=beta" }
List all disks on a bare metal server
This request lists all 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.
GET /bare_metal_servers/{bare_metal_server_id}/disks
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/disks?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServerDisksOptions{ BareMetalServerID: &bareMetalServerId, } bareMetalServerDiskCollection, response, err := vpcService.ListBareMetalServerDisks(options)
ListBareMetalServerDisksOptions listBareMetalServerDisksOptions = new ListBareMetalServerDisksOptions.Builder() .bareMetalServerId(bareMetalServerId) .build(); Response<BareMetalServerDiskCollection> response = vpcService.listBareMetalServerDisks(listBareMetalServerDisksOptions).execute(); BareMetalServerDiskCollection bareMetalServerDiskCollection = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, }; const response = await vpcService.listBareMetalServerDisks(params)
bare_metal_server_disk_collection = service.list_bare_metal_server_disks( bare_metal_server_id=bare_metal_server_id).get_result()
Response
Collection of the bare metal server's disks
Status Code
The disks were retrieved successfully.
A bare metal server with the specified identifier could not be found.
{ "disks": [ { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk", "size": 960 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-86003aba-47db-4d07-bd76-62e00cca83e5", "id": "2302-86003aba-47db-4d07-bd76-62e00cca83e5", "interface_type": "nvme", "name": "elderly-mountain-trout-opponent", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "id": "2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "interface_type": "nvme", "name": "could-kilt-twisty-unloaded", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-e544d72d-ca08-4924-b748-a8f67b66286d", "id": "2302-e544d72d-ca08-4924-b748-a8f67b66286d", "interface_type": "nvme", "name": "wildcat-impromptu-dribble-hesitate", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "id": "2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "interface_type": "nvme", "name": "imperfect-stimulate-culpable-thumb", "resource_type": "bare_metal_server_disk", "size": 3200 } ] }
Retrieve a bare metal server disk
This request retrieves a single disk specified by the identifier in the URL.
GET /bare_metal_servers/{bare_metal_server_id}/disks/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerDiskOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerDiskId, } bareMetalServerDisk, response, err := vpcService.GetBareMetalServerDisk(options)
GetBareMetalServerDiskOptions getBareMetalServerDiskOptions = new GetBareMetalServerDiskOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerDiskId) .build(); Response<BareMetalServerDisk> response = vpcService.getBareMetalServerDisk(getBareMetalServerDiskOptions).execute(); BareMetalServerDisk bareMetalServerDisk = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, id: bareMetalServerDiskId, }; const response = await vpcService.getBareMetalServerDisk(params)
bare_metal_server_disk = service.get_bare_metal_server_disk( bare_metal_server_id=bare_metal_server_id, id=bare_metal_disk_id).get_result()
Response
The date and time that the disk was created
The URL for this bare metal server disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this bare metal server disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The disk interface used for attaching the disk:
fcp
: Attached using Fiber Channel Protocolsata
: Attached using Serial Advanced Technology Attachmentnvme
: Attached using Non-Volatile Memory Express
The enumerated values for this property may expand in the future.
Possible values: [
fcp
,nvme
,sata
]The name for this bare metal server disk. The name is unique across all disks on the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-disk
The resource type
Possible values: [
bare_metal_server_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
Possible values: 1 ≤ value ≤ 100000
Example:
100
Status Code
The disk was retrieved successfully.
A bare metal server disk with the specified identifier could not be found.
{ "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "opponent-delude-slang-knoll", "resource_type": "bare_metal_server_disk", "size": 960 }
Update a bare metal server disk
This request updates the bare metal server disk with the information in a provided patch.
PATCH /bare_metal_servers/{bare_metal_server_id}/disks/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server disk identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server disk patch
The name for this bare metal server disk. The name must not be used by another disk on the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-disk-updated
curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/disks/$disk_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-disk-updated" }'
bareMetalServerDiskPatchModel := &vpcv1.BareMetalServerDiskPatch{} bareMetalServerDiskPatchModel.Name = &[]string{"my-bare-metal-server-disk-update"}[0] bareMetalServerDiskPatchModelAsPatch, asPatchErr := bareMetalServerDiskPatchModel.AsPatch() options := &vpcv1.UpdateBareMetalServerDiskOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerDiskId, BareMetalServerDiskPatch: bareMetalServerDiskPatchModelAsPatch, } bareMetalServerDisk, response, err := vpcService.UpdateBareMetalServerDisk(options)
BareMetalServerDiskPatch bareMetalServerDiskPatchModel = new BareMetalServerDiskPatch.Builder() .name("my-bare-metal-server-disk-update") .build(); Map<String, Object> bareMetalServerDiskPatchModelAsPatch = bareMetalServerDiskPatchModel.asPatch(); UpdateBareMetalServerDiskOptions updateBareMetalServerDiskOptions = new UpdateBareMetalServerDiskOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerDiskId) .bareMetalServerDiskPatch(bareMetalServerDiskPatchModelAsPatch) .build(); Response<BareMetalServerDisk> response = vpcService.updateBareMetalServerDisk(updateBareMetalServerDiskOptions).execute(); BareMetalServerDisk bareMetalServerDisk = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, id: bareMetalServerDiskId, name: 'my-bare-metal-server-disk-updated', }; const response = await vpcService.updateBareMetalServerDisk(params)
bare_metal_server_disk_patch_model = { 'name': 'my-bare-metal-server-disk', } bare_metal_server_disk = service.update_bare_metal_server_disk( bare_metal_server_id=bare_metal_server_id, id=bare_metal_disk_id, bare_metal_server_disk_patch=bare_metal_server_disk_patch_model ).get_result()
Response
The date and time that the disk was created
The URL for this bare metal server disk
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/disks/10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this bare metal server disk
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The disk interface used for attaching the disk:
fcp
: Attached using Fiber Channel Protocolsata
: Attached using Serial Advanced Technology Attachmentnvme
: Attached using Non-Volatile Memory Express
The enumerated values for this property may expand in the future.
Possible values: [
fcp
,nvme
,sata
]The name for this bare metal server disk. The name is unique across all disks on the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-disk
The resource type
Possible values: [
bare_metal_server_disk
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the disk in GB (gigabytes)
Possible values: 1 ≤ value ≤ 100000
Example:
100
Status Code
The bare metal server disk was updated successfully.
An invalid bare metal server disk patch was provided.
The bare metal server disk is not allowed to be updated.
A bare metal server disk with the specified identifier could not be found for the specified bare metal server.
{ "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "my-disk-updated", "resource_type": "bare_metal_server_disk", "size": 960 }
List all network attachments on a bare metal server
This request lists all 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.
GET /bare_metal_servers/{bare_metal_server_id}/network_attachments
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServerNetworkAttachmentsOptions{ BareMetalServerID: &bareMetalServerId, } bareMetalServerNetworkAttachmentCollection, response, err := vpcService.ListBareMetalServerNetworkAttachments(options)
ListBareMetalServerNetworkAttachmentsOptions listBareMetalServerNetworkAttachmentsOptions = new ListBareMetalServerNetworkAttachmentsOptions.Builder() .bareMetalServerId(bareMetalServerId) .build(); Response<BareMetalServerNetworkAttachmentCollection> response = vpcService.listBareMetalServerNetworkAttachments(listBareMetalServerNetworkAttachmentsOptions).execute(); BareMetalServerNetworkAttachmentCollection bareMetalServerNetworkAttachmentCollection = response.getResult();
const response = await vpcService.ListBareMetalServerNetworkAttachments({ bareMetalServerId });
bare_metal_server_network_attachment_collection = service.list_bare_metal_server_network_attachments( bare_metal_server_id, ).get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_attachments?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of bare metal server network attachments
network_attachments
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_attachments?start=d3e721fd-c988-4670-9927-dbd5e7b07fc6&limit=20
next
Status Code
The bare metal server network attachments were retrieved successfully.
A bare metal server with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf?limit=20" }, "limit": 20, "network_attachments": [ { "$ref": "#/components/schemas/BareMetalServerNetworkAttachment/example" } ], "total_count": 1 }
Create a network attachment on a bare metal server
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.
POST /bare_metal_servers/{bare_metal_server_id}/network_attachments
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.create
Generated for each virtual network interface created
is.virtual-network-interface.virtual-network-interface.attach
Generated for:
- each virtual network interface being attached to a bare metal server network attachment
- each virtual network interface for each reserved IP being attached to it
- each virtual network interface for each security group being attached to it
is.bare-metal-server.network-attachment.attach
Generated for each virtual network interface being attached to a bare metal server network attachment
is.bare-metal-server.network-attachment.create
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to a new virtual network interface
is.security-group.security-group.attach
Generated for each security group being attached to a new virtual network interface
is.subnet.subnet.update
Generated for each reserved IP created
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server network attachment prototype object
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
ofs390x
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_vlans
.- Must use an IEEE 802.1Q tag.
- Not supported on bare metal servers with a
cpu.architecture
ofs390x
Allowable values: [
pci
,vlan
]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.
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
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
ofs390x
- Has an
Allowable values: [
pci
]The VLAN IDs to allow for
vlan
attachments using this PCI attachment.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
Default:
[]
One of
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "interface_type": "vlan", "name": "my-vlan-network-attachment", "virtual_network_interface": { "id": "0767-fa41aecb-4f21-423d-8082-630bfba1e1d9" }, "vlan": 4 }'
virtualNetworkInterfaceModel := &vpcv1.BareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfaceIdentity{ ID: &virtualNetworkInterfaceId, } bareMetalServerNetworkAttachmentPrototypeModel := &vpcv1.BareMetalServerNetworkAttachmentPrototypeBareMetalServerNetworkAttachmentByPciPrototype{ InterfaceType: &[]string{"pci"}[0], VirtualNetworkInterface: virtualNetworkInterfaceModel, Name: &[]string{"my-network-attachment"}[0], } options := &vpcv1.CreateBareMetalServerNetworkAttachmentOptions{ BareMetalServerID: &bareMetalServerId, BareMetalServerNetworkAttachmentPrototype: bareMetalServerNetworkAttachmentPrototypeModel, } bareMetalServerNetworkAttachment, response, err := vpcService.CreateBareMetalServerNetworkAttachment(options)
BareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfacePrototypeBareMetalServerNetworkAttachmentContext bareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceModel = new BareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceVirtualNetworkInterfacePrototypeBareMetalServerNetworkAttachmentContext.Builder() .id(virtualNetworkInterfaceId); .build(); BareMetalServerNetworkAttachmentPrototypeBareMetalServerNetworkAttachmentByPCIPrototype bareMetalServerNetworkAttachmentPrototypeModel = new BareMetalServerNetworkAttachmentPrototypeBareMetalServerNetworkAttachmentByPCIPrototype.Builder() .virtualNetworkInterface(bareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceModel) .name("my-network-attachment") .interfaceType("pci") .build(); CreateBareMetalServerNetworkAttachmentOptions createBareMetalServerNetworkAttachmentOptions = new CreateBareMetalServerNetworkAttachmentOptions.Builder() .bareMetalServerId(bareMetalServerId) .bareMetalServerNetworkAttachmentPrototype(bareMetalServerNetworkAttachmentPrototypeModel) .build(); Response<BareMetalServerNetworkAttachment> response = vpcService.createBareMetalServerNetworkAttachment(createBareMetalServerNetworkAttachmentOptions).execute(); BareMetalServerNetworkAttachment bareMetalServerNetworkAttachment = response.getResult();
const bareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceModel = { id: virtualNetworkInterfaceId, }; const bareMetalServerNetworkAttachmentPrototypeModel = { virtual_network_interface: bareMetalServerNetworkAttachmentPrototypeVirtualNetworkInterfaceModel, name: 'my-network-attachment', interface_type: 'pci', }; const params = { bareMetalServerId: bareMetalServerId, bareMetalServerNetworkAttachmentPrototype: bareMetalServerNetworkAttachmentPrototypeModel, }; const response = await vpcService.createBareMetalServerNetworkAttachment(params);
subnet_identity_model = {} subnet_identity_model['id'] = subnetId bare_metal_server_network_attachment_prototype_virtual_network_interface_model = {} bare_metal_server_network_attachment_prototype_virtual_network_interface_model['name'] = 'my-virtual-network-interface' bare_metal_server_network_attachment_prototype_virtual_network_interface_model['subnet'] = subnet_identity_model bare_metal_server_network_attachment_prototype_model = {} bare_metal_server_network_attachment_prototype_model['name'] = 'my-bare-metal-server-network-attachment' bare_metal_server_network_attachment_prototype_model['virtual_network_interface'] = bare_metal_server_network_attachment_prototype_virtual_network_interface_model bare_metal_server_network_attachment_prototype_model['interface_type'] = 'pci' bare_metal_server_network_attachment_prototype = bare_metal_server_network_attachment_prototype_model bare_metal_server_network_attachment = _service.create_bare_metal_server_network_attachment( bare_metal_server_id, bare_metal_server_network_attachment_prototype, ).get_result()
Response
The date and time that the bare metal server network attachment was created
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_vlans
.- Must use an IEEE 802.1Q tag.
The enumerated values for this property may expand in the future.
Possible values: [
pci
,vlan
]The lifecycle state of the bare metal server network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The port speed for this bare metal server network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The bare metal server network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this bare metal server network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
The VLAN IDs allowed for
vlan
attachments using this PCI attachment.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
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.
- Has an
Possible values: [
pci
]
One of
Status Code
The bare metal server network attachment was created successfully.
An invalid bare metal server network attachment prototype object was provided.
A bare metal server with the specified identifier could not be found.
{ "$ref": "#/components/schemas/BareMetalServerNetworkAttachment/example" }
Delete a bare metal server network attachment
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.
DELETE /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.bare-metal-server.network-attachment.delete
is.virtual-network-interface.virtual-network-interface.detach
Generated for the attached virtual network interface, and also generated for each reserved IP that was attached to the virtual network interface if the virtual network interface had
auto_delete
set totrue
is.virtual-network-interface.virtual-network-interface.delete
Generated when the virtual network interface had
auto_delete
set totrue
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.security-group.security-group.detach
Generated for each security group that was attached to a virtual network interface that had
auto_delete
set totrue
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteBareMetalServerNetworkAttachmentOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkAttachmentId, } response, err := vpcService.DeleteBareMetalServerNetworkAttachment(options)
DeleteBareMetalServerNetworkAttachmentOptions deleteBareMetalServerNetworkAttachmentOptions = new DeleteBareMetalServerNetworkAttachmentOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkAttachmentId) .build(); Response<Void> response = vpcService.deleteBareMetalServerNetworkAttachment(deleteBareMetalServerNetworkAttachmentOptions).execute();
const response = await vpcService.deleteBareMetalServerNetworkAttachment({ bareMetalServerId, bareMetalServerNetworkAttachmentId, });
response = vpc_service.delete_bare_metal_server_network_attachment( bare_metal_server_id=bare_metal_server_id, id=bare_metal_server_network_attachment_id, )
Retrieve a bare metal server network attachment
This request retrieves a single bare metal server network attachment specified by the identifier in the URL.
GET /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerNetworkAttachmentOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkAttachmentId, } bareMetalServerNetworkAttachment, response, err := vpcService.GetBareMetalServerNetworkAttachment(options)
GetBareMetalServerNetworkAttachmentOptions getBareMetalServerNetworkAttachmentOptions = new GetBareMetalServerNetworkAttachmentOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkAttachmentId) .build(); Response<BareMetalServerNetworkAttachment> response = vpcService.getBareMetalServerNetworkAttachment(getBareMetalServerNetworkAttachmentOptions).execute(); BareMetalServerNetworkAttachment bareMetalServerNetworkAttachment = response.getResult();
const response = await vpcService.getBareMetalServerNetworkAttachment({ bareMetalServerId, bareMetalServerNetworkAttachmentId, });
response = vpc_service.get_bare_metal_server_network_attachment( bare_metal_server_id=bare_metal_server_id, id=bare_metal_server_network_attachment_id, ) bare_metal_server_network_attachment = response.get_result()
Response
The date and time that the bare metal server network attachment was created
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_vlans
.- Must use an IEEE 802.1Q tag.
The enumerated values for this property may expand in the future.
Possible values: [
pci
,vlan
]The lifecycle state of the bare metal server network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The port speed for this bare metal server network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The bare metal server network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this bare metal server network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
The VLAN IDs allowed for
vlan
attachments using this PCI attachment.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
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.
- Has an
Possible values: [
pci
]
One of
Status Code
The bare metal server network attachment was retrieved successfully.
A bare metal server network attachment with the specified identifier could not be found.
{ "$ref": "#/components/schemas/BareMetalServerNetworkAttachment/example" }
Update a bare metal server network attachment
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.
PATCH /bare_metal_servers/{bare_metal_server_id}/network_attachments/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server network attachment patch
The VLAN IDs to allow for
vlan
attachments using this PCI attachment, replacing any existing VLAN IDs. The specified values must include IDs for allvlan
attachments currently using this PCI attachment.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
The name for this network attachment. The name must not be used by another network attachment for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment-updated
curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments/$network_attachment_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "allowed_vlans": [ 4,5,6 ] }'
bareMetalServerNetworkAttachmentPatchModel := &vpcv1.BareMetalServerNetworkAttachmentPatch{ Name: &[]string{"my-network-attachment-update"}[0], } bareMetalServerNetworkAttachmentPatchModelAsPatch, asPatchErr := bareMetalServerNetworkAttachmentPatchModel.AsPatch() options := &vpcv1.UpdateBareMetalServerNetworkAttachmentOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkAttachmentId, BareMetalServerNetworkAttachmentPatch: bareMetalServerNetworkAttachmentPatchModelAsPatch, } bareMetalServerNetworkAttachment, response, err := vpcService.UpdateBareMetalServerNetworkAttachment(options)
BareMetalServerNetworkAttachmentPatch bareMetalServerNetworkAttachmentPatchModel = new BareMetalServerNetworkAttachmentPatch.Builder() .name("my-network-attachment-update") .build(); Map<String, Object> bareMetalServerNetworkAttachmentPatchModelAsPatch = bareMetalServerNetworkAttachmentPatchModel.asPatch(); UpdateBareMetalServerNetworkAttachmentOptions updateBareMetalServerNetworkAttachmentOptions = new UpdateBareMetalServerNetworkAttachmentOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkAttachmentId) .bareMetalServerNetworkAttachmentPatch(bareMetalServerNetworkAttachmentPatchModelAsPatch) .build(); Response<BareMetalServerNetworkAttachment> response = vpcService.updateBareMetalServerNetworkAttachment(updateBareMetalServerNetworkAttachmentOptions).execute(); BareMetalServerNetworkAttachment bareMetalServerNetworkAttachment = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, id: bareMetalServerNetworkAttachmentId, name: 'my-network-attachment-updated', }; const response = await vpcService.updateBareMetalServerNetworkAttachment(params);
bare_metal_server_network_attachment_patch_model = { 'name'='my-network-attachment-update' } response = vpc_service.update_bare_metal_server_network_attachment( bare_metal_server_id=bare_metal_server_id, id=bare_metal_server_network_attachment_id, bare_metal_server_network_attachment_patch=bare_metal_server_network_attachment_patch_model, ) bare_metal_server_network_attachment = response.get_result()
Response
The date and time that the bare metal server network attachment was created
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_vlans
.- Must use an IEEE 802.1Q tag.
The enumerated values for this property may expand in the future.
Possible values: [
pci
,vlan
]The lifecycle state of the bare metal server network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The port speed for this bare metal server network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The bare metal server network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this bare metal server network attachment
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
The VLAN IDs allowed for
vlan
attachments using this PCI attachment.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
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.
- Has an
Possible values: [
pci
]
One of
Status Code
The bare metal server network attachment was updated successfully.
An invalid bare metal server network attachment patch was provided.
A bare metal server network attachment with the specified identifier could not be found.
{ "$ref": "#/components/schemas/BareMetalServerNetworkAttachment/example" }
List all network interfaces on a bare metal server
This request lists all 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.
GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServerNetworkInterfacesOptions{ BareMetalServerID: &bareMetalServerId, } bareMetalServerNetworkInterfaceCollection, response, err := vpcService.ListBareMetalServerNetworkInterfaces(options)
ListBareMetalServerNetworkInterfacesOptions listBareMetalServerNetworkInterfacesOptions = new ListBareMetalServerNetworkInterfacesOptions.Builder() .bareMetalServerId(bareMetalServerId) .build(); Response<BareMetalServerNetworkInterfaceCollection> response = vpcService.listBareMetalServerNetworkInterfaces(listBareMetalServerNetworkInterfacesOptions).execute(); BareMetalServerNetworkInterfaceCollection bareMetalServerNetworkInterfaceCollection = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, }; const response = await vpcService.listBareMetalServerNetworkInterfaces(params)
bare_metal_server_network_interface_collection = service.list_bare_metal_server_network_interfaces( bare_metal_server_id=bare_metal_server_id).get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of bare metal server network interfaces
network_interfaces
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces?start=d3e721fd-c988-4670-9927-dbd5e7b07fc6&limit=20
next
Status Code
The bare metal server network interfaces were retrieved successfully.
A bare metal server with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf?limit=20" }, "limit": 20, "network_interfaces": [ { "allow_ip_spoofing": false, "allowed_vlans": [ 4 ], "created_at": "2021-05-21T06:09:15.000Z", "enable_infrastructure_nat": false, "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "interface_type": "pci", "mac_address": "02:09:04:00:C4:6A", "name": "my-primary-network-interface", "port_speed": 100000, "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.0.1.9", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "id": "r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "name": "my-security-group", "resource_type": "security_group" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" }, "type": "primary" }, { "allow_interface_to_float": true, "allow_ip_spoofing": false, "created_at": "2021-05-21T06:09:15.000Z", "enable_infrastructure_nat": false, "floating_ips": [ { "address": "192.0.2.3", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ec9fa26d-8baa-4938-a056-990ee016d224", "id": "ec9fa26d-8baa-4938-a056-990ee016d224", "name": "my-floating-ip-2" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-7a14a055-ad88-41fe-8de2-b2f977054251", "id": "2302-7a14a055-ad88-41fe-8de2-b2f977054251", "interface_type": "vlan", "mac_address": "02:09:04:00:C4:6B", "name": "my-vlan-interface", "port_speed": 100000, "primary_ip": { "address": "10.0.1.10", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749", "id": "948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.0.1.10", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "id": "r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "name": "my-security-group", "resource_type": "security_group" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" }, "type": "secondary", "vlan": 4 } ], "total_count": 2 }
Create a network interface on a bare metal server
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.
POST /bare_metal_servers/{bare_metal_server_id}/network_interfaces
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.bare-metal-server.network-interface.create
is.bare-metal-server.network-interface.attach
Generated for each resource attached to the bare metal server network interface:
- a security group
- a reserved IP
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.subnet.reserved-ip.attach
Generated for each reserved IP attached to the bare metal server network interface
is.security-group.security-group.attach
Generated for each security group attached to the bare metal server network interface
is.subnet.subnet.update
Generated for each reserved IP created
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server network interface prototype object
The interface type:
hipersocket
: a virtual device that provides high-speed TCP/IP connectivity within as390x
based system- Not supported on bare metal servers with a
cpu.architecture
ofamd64
- Not supported on bare metal servers with a
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
ofs390x
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_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
ofs390x
Allowable values: [
hipersocket
,pci
,vlan
]The associated subnet
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
subnet
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.
Default:
false
Example:
true
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 befalse
.interface_type
must not behipersocket
.
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.
Default:
true
Example:
true
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-bare-metal-server-network-interface
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.
primary_ip
The security groups to use for this bare metal server network interface. If unspecified, the VPC's default security group is used.
Possible values: contains only unique items
Examples:Viewsecurity_groups
hipersocket
: a virtual network device that provides high-speed TCP/IP connectivity within as390x
based system.- Not supported on bare metal servers with a
cpu.architecture
ofamd64
- Not supported on bare metal servers with a
Allowable values: [
hipersocket
]
One of
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "interface_type": "vlan", "name": "my-vlan", "subnet": { "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5" }, "vlan": 4 }'
subnetIdentityModel := &vpcv1.SubnetIdentityByID{ ID: &subnetId, } bareMetalServerNetworkInterfacePrototypeModel := &vpcv1.BareMetalServerNetworkInterfacePrototypeBareMetalServerNetworkInterfaceByPciPrototype{ InterfaceType: &[]string{"pci"}[0], Subnet: subnetIdentityModel, Name: &[]string{"my-network-interface"}[0], } options := &vpcv1.CreateBareMetalServerNetworkInterfaceOptions{ BareMetalServerID: &bareMetalServerId, BareMetalServerNetworkInterfacePrototype: bareMetalServerNetworkInterfacePrototypeModel, } bareMetalServerNetworkInterface, response, err := vpcService.CreateBareMetalServerNetworkInterface(options)
SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); BareMetalServerNetworkInterfacePrototypeBareMetalServerNetworkInterfaceByVLANPrototype bareMetalServerNetworkInterfacePrototypeModel = new BareMetalServerNetworkInterfacePrototypeBareMetalServerNetworkInterfaceByVLANPrototype.Builder() .interfaceType("vlan") .name("my-network-interface") .enableInfrastructureNat(true) .subnet(subnetIdentityModel) .vlan(Long.valueOf("4")) .build(); CreateBareMetalServerNetworkInterfaceOptions createBareMetalServerNetworkInterfaceOptions = new CreateBareMetalServerNetworkInterfaceOptions.Builder() .bareMetalServerId(bareMetalServerId) .bareMetalServerNetworkInterfacePrototype(bareMetalServerNetworkInterfacePrototypeModel) .build(); Response<BareMetalServerNetworkInterface> response = vpcService.createBareMetalServerNetworkInterface(createBareMetalServerNetworkInterfaceOptions).execute(); BareMetalServerNetworkInterface bareMetalServerNetworkInterface = response.getResult();
const subnetIdentityModel = { id: subnetId, }; const bareMetalServerNetworkInterfacePrototypeModel = { allow_ip_spoofing: true, enable_infrastructure_nat: true, interface_type: 'vlan', name: 'my-network-interface', subnet: subnetIdentityModel, allow_interface_to_float: false, vlan: 4, }; const params = { bareMetalServerId: bareMetalServerId, bareMetalServerNetworkInterfacePrototype: bareMetalServerNetworkInterfacePrototypeModel, }; const response = await vpcService.createBareMetalServerNetworkInterface(params)
bare_metal_server_network_interface_prototype_model = { 'interface_type': 'vlan', 'subnet': { 'id': subnetId }, 'vlan': 4, } bare_metal_server_network_interface = service.create_bare_metal_server_network_interface( bare_metal_server_id=bare_metal_server_id, bare_metal_server_network_interface_prototype= bare_metal_server_network_interface_prototype_model).get_result()
Response
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.
Example:
true
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.
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 befalse
.interface_type
must not behipersocket
.
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.
Example:
true
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The interface type:
hipersocket
: a virtual device that provides high-speed TCP/IP connectivity within as390x
based systempci
: 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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_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.
Possible values: [
hipersocket
,pci
,vlan
]The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be an empty string.
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.
Possible values: 0 ≤ length ≤ 17, Value must match regular expression
^$|^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:04:00:C4:6A
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
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.
Possible values: [
primary
,secondary
]Example:
primary
hipersocket
: a virtual network device that provides high-speed TCP/IP connectivity within as390x
based system.
Possible values: [
hipersocket
]
One of
Status Code
The bare metal server network interface was created successfully.
An invalid bare metal server network interface prototype object was provided.
The bare metal server network interface is not allowed to be created.
A bare metal server with the specified identifier could not be found.
{ "allow_ip_spoofing": false, "allowed_vlans": [ 4 ], "created_at": "2021-05-21T06:09:15.000Z", "enable_infrastructure_nat": false, "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "interface_type": "pci", "mac_address": "02:09:04:00:C4:6A", "name": "my-primary-network-interface", "port_speed": 100000, "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.0.1.9", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "id": "r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "name": "my-security-group", "resource_type": "security_group" } ], "status": "pending", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" }, "type": "primary" }
Delete a bare metal server network interface
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.
DELETE /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.bare-metal-server.network-interface.delete
is.bare-metal-server.network-interface.detach
Generated for each resource that was attached to this bare metal server network interface:
- floating IPs
- reserved IPs
- security groups
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to this bare metal server network interface
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to this bare metal server network interface
is.security-group.security-group.detach
Generated for each security group that was attached to this bare metal server network interface
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to this bare metal server network interfaceis.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to this bare metal server network interface
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteBareMetalServerNetworkInterfaceOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkInterfaceId, } response, err := vpcService.DeleteBareMetalServerNetworkInterface(options)
DeleteBareMetalServerNetworkInterfaceOptions deleteBareMetalServerNetworkInterfaceOptions = new DeleteBareMetalServerNetworkInterfaceOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkInterfaceId) .build(); Response<Void> response = vpcService.deleteBareMetalServerNetworkInterface(deleteBareMetalServerNetworkInterfaceOptions).execute();
const params = { bareMetalServerId: bareMetalServerId, id: networkInterfaceId, }; const response = await vpcService.deleteBareMetalServerNetworkInterface(params)
response = service.delete_bare_metal_server_network_interface( bare_metal_server_id=bare_metal_server_id, id=network_interface_id).get_result()
Retrieve a bare metal server network interface
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.
GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerNetworkInterfaceOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkInterfaceId, } bareMetalServerNetworkInterface, response, err := vpcService.GetBareMetalServerNetworkInterface(options)
GetBareMetalServerNetworkInterfaceOptions getBareMetalServerNetworkInterfaceOptions = new GetBareMetalServerNetworkInterfaceOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkInterfaceId) .build(); Response<BareMetalServerNetworkInterface> response = vpcService.getBareMetalServerNetworkInterface(getBareMetalServerNetworkInterfaceOptions).execute(); BareMetalServerNetworkInterface bareMetalServerNetworkInterface = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, id: networkInterfaceId, }; const response = await vpcService.getBareMetalServerNetworkInterface(params)
bare_metal_server_network_interface = service.get_bare_metal_server_network_interface( bare_metal_server_id=bare_metal_server_id, id=network_interface_id).get_result()
Response
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.
Example:
true
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.
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 befalse
.interface_type
must not behipersocket
.
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.
Example:
true
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The interface type:
hipersocket
: a virtual device that provides high-speed TCP/IP connectivity within as390x
based systempci
: 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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_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.
Possible values: [
hipersocket
,pci
,vlan
]The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be an empty string.
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.
Possible values: 0 ≤ length ≤ 17, Value must match regular expression
^$|^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:04:00:C4:6A
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
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.
Possible values: [
primary
,secondary
]Example:
primary
hipersocket
: a virtual network device that provides high-speed TCP/IP connectivity within as390x
based system.
Possible values: [
hipersocket
]
One of
Status Code
The bare metal server network interface was retrieved successfully.
A bare metal server network interface with the specified identifier could not be found.
{ "allow_ip_spoofing": true, "allowed_vlans": [ 4 ], "created_at": "2021-05-21T06:09:15.000Z", "enable_infrastructure_nat": true, "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "interface_type": "pci", "mac_address": "02:09:04:00:C4:6A", "name": "my-primary-network-interface", "port_speed": 100000, "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.0.1.9", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "id": "r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "name": "my-security-group", "resource_type": "security_group" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" }, "type": "primary" }
Update a bare metal server network interface
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.
PATCH /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server network interface patch
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.
Example:
true
The VLAN IDs to allow for
vlan
interfaces using this PCI interface, replacing any existing VLAN IDs. The specified values must include IDs for allvlan
interfaces currently using this PCI interface.Possible values: number of items ≥ 0, contains only unique items, 1 ≤ value ≤ 4094
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 befalse
.interface_type
must not behipersocket
.
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.
Example:
true
The name for this bare metal server network interface. The name must not be used by another network interface on the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-bare-metal-server-network-interface
curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "allow_ip_spoofing": true, "allowed_vlans": [ 4,5,6 ] }'
bareMetalServerNetworkInterfacePatchModel := &vpcv1.BareMetalServerNetworkInterfacePatch{ Name: &[]string{"my-network-interface-update"}[0], } bareMetalServerNetworkInterfacePatchModelAsPatch, asPatchErr := bareMetalServerNetworkInterfacePatchModel.AsPatch() options := &vpcv1.UpdateBareMetalServerNetworkInterfaceOptions{ BareMetalServerID: &bareMetalServerId, ID: &bareMetalServerNetworkInterfaceId, BareMetalServerNetworkInterfacePatch: bareMetalServerNetworkInterfacePatchModelAsPatch, } bareMetalServerNetworkInterface, response, err := vpcService.UpdateBareMetalServerNetworkInterface(options)
BareMetalServerNetworkInterfacePatch bareMetalServerNetworkInterfacePatchModel = new BareMetalServerNetworkInterfacePatch.Builder() .name("my-network-interface-updated") .build(); Map<String, Object> bareMetalServerNetworkInterfacePatchModelAsPatch = bareMetalServerNetworkInterfacePatchModel.asPatch(); UpdateBareMetalServerNetworkInterfaceOptions updateBareMetalServerNetworkInterfaceOptions = new UpdateBareMetalServerNetworkInterfaceOptions.Builder() .bareMetalServerId(bareMetalServerId) .id(bareMetalServerNetworkInterfaceId) .bareMetalServerNetworkInterfacePatch(bareMetalServerNetworkInterfacePatchModelAsPatch) .build(); Response<BareMetalServerNetworkInterface> response = vpcService.updateBareMetalServerNetworkInterface(updateBareMetalServerNetworkInterfaceOptions).execute(); BareMetalServerNetworkInterface bareMetalServerNetworkInterface = response.getResult();
const params = { bareMetalServerId: dict.createdBareMetalServerId, id: networkInterfaceId, allowIpSpoofing: true, allowedVlans: [4], enableInfrastructureNat: true, name: 'my-network-interface-updated', }; const response = await vpcService.updateBareMetalServerNetworkInterface(params)
bare_metal_server_network_interface_patch_model = { 'name': 'my-network-interface-updated' } bare_metal_server_network_interface = service.update_bare_metal_server_network_interface( bare_metal_server_id=bare_metal_server_id, id=network_interface_id, bare_metal_server_network_interface_patch= bare_metal_server_network_interface_patch_model).get_result()
Response
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.
Example:
true
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.
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 befalse
.interface_type
must not behipersocket
.
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.
Example:
true
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The interface type:
hipersocket
: a virtual device that provides high-speed TCP/IP connectivity within as390x
based systempci
: 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.
- Has an
vlan
: a virtual device, used through apci
device that has thevlan
in its array ofallowed_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.
Possible values: [
hipersocket
,pci
,vlan
]The MAC address of this bare metal server network interface. If the MAC address has not yet been selected, the value will be an empty string.
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.
Possible values: 0 ≤ length ≤ 17, Value must match regular expression
^$|^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:04:00:C4:6A
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
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.
Example:
1000
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
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.
Possible values: [
primary
,secondary
]Example:
primary
hipersocket
: a virtual network device that provides high-speed TCP/IP connectivity within as390x
based system.
Possible values: [
hipersocket
]
One of
Status Code
The bare metal server network interface was updated successfully.
An invalid bare metal server network interface patch was provided.
The bare metal server network interface is not allowed to be updated.
A bare metal server network interface with the specified identifier could not be found.
{ "allow_ip_spoofing": false, "allowed_vlans": [ 4, 5, 6 ], "created_at": "2021-05-21T06:09:15.000Z", "enable_infrastructure_nat": false, "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/181b8670-52bf-47af-a5ca-7aff7f3824d1", "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1", "name": "my-floating-ip" } ], "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "interface_type": "pci", "mac_address": "02:09:04:00:C4:6A", "name": "my-primary-network-interface", "port_speed": 100000, "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.0.1.9", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "id": "r134-c9000732-a9c5-4e2c-9582-3689ac4e8104", "name": "my-security-group", "resource_type": "security_group" } ], "status": "available", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" }, "type": "primary" }
List all floating IPs associated with a bare metal server network interface
This request lists all 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
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/floating_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServerNetworkInterfaceFloatingIpsOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId, } floatingIPUnpaginatedCollection, response, err := vpcService.ListBareMetalServerNetworkInterfaceFloatingIps(options)
ListBareMetalServerNetworkInterfaceFloatingIpsOptions listBareMetalServerNetworkInterfaceFloatingIpsOptions = new ListBareMetalServerNetworkInterfaceFloatingIpsOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .build(); Response<FloatingIPUnpaginatedCollection> response = vpcService.listBareMetalServerNetworkInterfaceFloatingIps(listBareMetalServerNetworkInterfaceFloatingIpsOptions).execute(); FloatingIPUnpaginatedCollection floatingIpUnpaginatedCollection = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, }; const response = await vpcService.listBareMetalServerNetworkInterfaceFloatingIps(params)
floating_ip_unpaginated_collection = service.list_bare_metal_server_network_interface_floating_ips( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id).get_result()
Response
Collection of floating IPs
Status Code
The associated floating IPs were retrieved successfully.
A bare metal server network interface with the specified identifier could not be found.
{ "floating_ips": [ { "address": "169.48.87.173", "created_at": "2021-05-21T08:49:23.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf/floating_ips/r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "id": "r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "name": "antiquity-growing-carefully-kept", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "status": "available", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } } ] }
Disassociate a floating IP from a bare metal server network interface
This request disassociates the specified floating IP from the specified bare metal server network interface
DELETE /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.RemoveBareMetalServerNetworkInterfaceFloatingIPOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId, ID: &floating, } response, err := vpcService.RemoveBareMetalServerNetworkInterfaceFloatingIP(options)
RemoveBareMetalServerNetworkInterfaceFloatingIpOptions removeBareMetalServerNetworkInterfaceFloatingIpOptions = new RemoveBareMetalServerNetworkInterfaceFloatingIpOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .id(floatingIpId) .build(); Response<Void> response = vpcService.removeBareMetalServerNetworkInterfaceFloatingIp(removeBareMetalServerNetworkInterfaceFloatingIpOptions).execute();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, id: floatingIpId, }; const response = await vpcService.removeBareMetalServerNetworkInterfaceFloatingIp(params)
response = service.remove_bare_metal_server_network_interface_floating_ip( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id, id=floating_ip_id).get_result()
Response
Status Code
The floating IP was disassociated successfully.
The specified floating IP could not be disassociated.
The floating IP is not allowed to be disassociated.
The specified floating IP address is not associated with the bare metal server network interface with the specified identifier
No Sample Response
Retrieve associated floating IP
This request retrieves a specified floating IP if it is associated with the bare metal server network interface specified in the URL
GET /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerNetworkInterfaceFloatingIPOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId, ID: &floatingIpId, } floatingIP, response, err := vpcService.GetBareMetalServerNetworkInterfaceFloatingIP(options)
GetBareMetalServerNetworkInterfaceFloatingIpOptions getBareMetalServerNetworkInterfaceFloatingIpOptions = new GetBareMetalServerNetworkInterfaceFloatingIpOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .id(floatingIpId) .build(); Response<FloatingIP> response = vpcService.getBareMetalServerNetworkInterfaceFloatingIp(getBareMetalServerNetworkInterfaceFloatingIpOptions).execute(); FloatingIP floatingIp = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, id: floatingIpId, }; const response = await vpcService.getBareMetalServerNetworkInterfaceFloatingIp(params)
floating_ip = service.get_bare_metal_server_network_interface_floating_ip( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id, id=floating_ip_id).get_result()
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The associated floating IP was retrieved successfully.
The floating IP address is not associated with a bare metal server network interface with the specified identifier
{ "address": "169.48.87.173", "created_at": "2021-05-21T08:49:23.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf/floating_ips/r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "id": "r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "name": "antiquity-growing-carefully-kept", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "status": "available", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } }
Associate a floating IP with a bare metal server network interface
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:
- not be required by another resource, such as a public gateway
- be in the same
zone
as the bare metal server
A request body is not required, and if provided, is ignored.
PUT /bare_metal_servers/{bare_metal_server_id}/network_interfaces/{network_interface_id}/floating_ips/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.AddBareMetalServerNetworkInterfaceFloatingIPOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId, ID: &floatingIpId, } floatingIP, response, err := vpcService.AddBareMetalServerNetworkInterfaceFloatingIP(options)
AddBareMetalServerNetworkInterfaceFloatingIpOptions addBareMetalServerNetworkInterfaceFloatingIpOptions = new AddBareMetalServerNetworkInterfaceFloatingIpOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .id(floatingIpId) .build(); Response<FloatingIP> response = vpcService.addBareMetalServerNetworkInterfaceFloatingIp(addBareMetalServerNetworkInterfaceFloatingIpOptions).execute(); FloatingIP floatingIp = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, id: floatingIpId, }; const response = await vpcService.addBareMetalServerNetworkInterfaceFloatingIp(params)
floating_ip = service.add_bare_metal_server_network_interface_floating_ip( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id, id=floating_ip_id).get_result()
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The floating IP was successfully associated with the bare metal server network interface.
The specified floating IP could not be associated with the specified bare metal server network interface.
The floating IP is not allowed to be associated.
The specified bare metal server network interface or floating IP could not be found.
{ "address": "169.48.87.173", "created_at": "2021-05-21T08:49:23.000Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf/floating_ips/r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "id": "r134-210655b7-d1e7-467a-9e51-97e23e0dc714", "name": "antiquity-growing-carefully-kept", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "status": "available", "target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } }
List the primary reserved IP for a bare metal server network interface
This request lists 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
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListBareMetalServerNetworkInterfaceIpsOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId } reservedIPs, response, err := vpcService.ListBareMetalServerNetworkInterfaceIps(options)
GetBareMetalServerNetworkInterfaceIpOptions getBareMetalServerNetworkInterfaceIpOptions = new GetBareMetalServerNetworkInterfaceIpOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .build(); Response<ReservedIPCollectionNetworkInterfaceContext> response = vpcService.getBareMetalServerNetworkInterfaceIp(getBareMetalServerNetworkInterfaceIpOptions).execute(); ReservedIPCollectionNetworkInterfaceContext reservedIPs = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, }; const response = await vpcService.listBareMetalServerNetworkInterfaceFloatingIps(params)
reserved_ips = service.list_bare_metal_server_network_interface_ips( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id).get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?limit=20
first
Collection of reserved IPs bound to a bare metal server network interface
Possible values: number of items ≤ 1
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?start=a404e343444b4e1095c9edba76672d67&limit=20
next
Status Code
The reserved IPs were retrieved successfully.
A bare metal server network interface with the specified identifier could not be found for the specified bare metal server.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?limit=50" }, "ips": [ { "address": "10.240.0.7", "auto_delete": false, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-network-interface", "resource_type": "network_interface" } } ], "limit": 50, "total_count": 1 }
Retrieve the primary reserved IP
This request retrieves 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/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The bare metal server network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id/ips/$reserved_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerNetworkInterfaceIPOptions{ BareMetalServerID: &bareMetalServerId, NetworkInterfaceID: &bareMetalServerNetworkInterfaceId ID: &reservedIpId, } reservedIP, response, err := vpcService.GetBareMetalServerNetworkInterfaceIP(options)
GetBareMetalServerNetworkInterfaceIpOptions getBareMetalServerNetworkInterfaceIpOptions = new GetBareMetalServerNetworkInterfaceIpOptions.Builder() .bareMetalServerId(bareMetalServerId) .networkInterfaceId(bareMetalServerNetworkInterfaceId) .id(reservedIPId) .build(); Response<ReservedIP> response = vpcService.getBareMetalServerNetworkInterfaceIp(getBareMetalServerNetworkInterfaceIpOptions).execute(); ReservedIP reservedIP = response.getResult();
const params = { bareMetalServerId: bareMetalServerId, networkInterfaceId: networkInterfaceId, id: reservedIpId, }; const response = await vpcService.getBareMetalServerNetworkInterfaceIP(params)
reserved_ip = service.get_bare_metal_server_network_interface_ip( bare_metal_server_id=bare_metal_server_id, network_interface_id=network_interface_id id=reserved_ip_id).get_result()
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The bound reserved IP was retrieved successfully.
The reserved IP address with the specified identifier could not be found
{ "address": "10.240.0.7", "auto_delete": false, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e", "id": "10c02d81-0ecb-4dc5-897d-28392913b81e", "name": "my-network-interface", "resource_type": "network_interface" } }
Delete a bare metal server
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.
DELETE /bare_metal_servers/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.bare-metal-server.bare-metal-server.delete
is.bare-metal-server.network-interface.delete
Generated for each network interface on the bare metal server
is.bare-metal-server.network-interface.detach
Generated for each network interface on the bare metal server
is.bare-metal-server.network-attachment.delete
Generated for each network attachment on the bare metal server
is.bare-metal-server.network-attachment.detach
Generated for each network attachment on the bare metal server
is.virtual-network-interface.virtual-network-interface.detach
Generated for:
- each attached virtual network interface
- each virtual network interface that had
auto_delete
set totrue
, for each attached reserved IP
is.virtual-network-interface.virtual-network-interface.delete
Generated for each virtual network interface that had
auto_delete
set totrue
is.floating-ip.floating-ip.detach
Generated for each floating IP that was attached to:
- a network interface on the bare metal server, or
- an virtual network interface that had
auto_delete
set totrue
is.security-group.security-group.detach
Generated for each security group that was attached to:
- a network interface on the bare metal server, or
- an virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to:
- a network interface on the bare metal server, or
- an virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteBareMetalServerOptions{ ID: &bareMetalServerId, } response, err := vpcService.DeleteBareMetalServer(options)
DeleteBareMetalServerOptions deleteBareMetalServerOptions = new DeleteBareMetalServerOptions.Builder() .id(bareMetalServerId) .build(); Response<Void> response = vpcService.deleteBareMetalServer(deleteBareMetalServerOptions).execute();
const params = { id: bareMetalServerId, }; const response = await vpcService.deleteBareMetalServer(params)
response = service.delete_bare_metal_server(id=bare_metal_server_id).get_result()
Retrieve a bare metal server
This request retrieves a single bare metal server specified by the identifier in the URL.
GET /bare_metal_servers/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerOptions{ ID: &bareMetalServerId, } bareMetalServer, response, err := vpcService.GetBareMetalServer(options)
GetBareMetalServerOptions getBareMetalServerOptions = new GetBareMetalServerOptions.Builder() .id(bareMetalServerId) .build(); Response<BareMetalServer> response = vpcService.getBareMetalServer(getBareMetalServerOptions).execute(); BareMetalServer bareMetalServer = response.getResult();
const params = { id: bareMetalServerId, }; const response = await vpcService.getBareMetalServer(params)
bare_metal_server = service.get_bare_metal_server( id=bare_metal_server_id).get_result()
Response
The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces
Possible values: 1 ≤ value ≤ 1000000
Example:
20000
The resource from which this bare metal server is booted.
The resources supported by this property may expand in the future.
Examples:ViewThe bare metal server CPU configuration
The date and time that the bare metal server was created
The CRN for this bare metal server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::bare-metal-server:1e09281b-f177-46fb-baf1-bc152b2e391a
The disks for this bare metal server, including any disks that are associated with the
boot_target
.Possible values: number of items ≥ 0
Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.
The URL for this bare metal server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this bare metal server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the bare metal server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 100000
Example:
1536
The name for this bare metal server. The name is unique across all bare metal servers in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server
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.
Possible values: number of items ≥ 1
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this bare metal server network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this bare metal server
The URL for this bare metal server profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles/bx2-metal-192x768
The name for this bare metal server profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-metal-192x768
The resource type
Possible values: [
bare_metal_server_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this bare metal server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
bare_metal_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this bare metal server:
deleting
: server is undergoing deletionfailed
: server is failed and not usable (seestatus_reasons
)maintenance
: server is undergoing maintenance (not usable)pending
: server is being provisioned and not yet usablerestarting
: server is restarting and not yet usablerunning
: server is powered onstarting
: server is starting and not yet usablestopped
: server is powered off
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,maintenance
,pending
,restarting
,running
,starting
,stopped
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The VPC this bare metal server resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this bare metal server resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The network attachments for this bare metal server, including the primary network attachment.
Possible values: number of items ≥ 0
The primary network attachment for this bare metal server.
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
Status Code
The bare metal server was retrieved successfully.
A bare metal server with the specified identifier could not be found.
{ "bandwidth": 100000, "boot_target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "name": "my-disk", "resource_type": "bare_metal_server_disk" }, "cpu": { "architecture": "amd64", "core_count": 96, "socket_count": 4, "threads_per_core": 2 }, "created_at": "2021-05-21T06:09:15.000Z", "crn": "crn:[...]", "disks": [ { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "updated-disk-name", "resource_type": "bare_metal_server_disk", "size": 960 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-86003aba-47db-4d07-bd76-62e00cca83e5", "id": "2302-86003aba-47db-4d07-bd76-62e00cca83e5", "interface_type": "nvme", "name": "elderly-mountain-trout-opponent", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "id": "2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "interface_type": "nvme", "name": "could-kilt-twisty-unloaded", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-e544d72d-ca08-4924-b748-a8f67b66286d", "id": "2302-e544d72d-ca08-4924-b748-a8f67b66286d", "interface_type": "nvme", "name": "wildcat-impromptu-dribble-hesitate", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "id": "2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "interface_type": "nvme", "name": "imperfect-stimulate-culpable-thumb", "resource_type": "bare_metal_server_disk", "size": 3200 } ], "enable_secure_boot": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "id": "2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 768, "name": "my-bare-metal-server", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "id": "2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.12", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/a053a8c6-ed22-4773-8120-4c0c67c8b64a", "id": "a053a8c6-ed22-4773-8120-4c0c67c8b64a", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "subnet-1", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "id": "2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.9", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "subnet-1", "resource_type": "subnet" } } ], "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768", "name": "bx2d-metal-192x768", "resource_type": "bare_metal_server_profile" }, "resource_group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "resource_type": "bare_metal_server", "status": "running", "status_reasons": [], "trusted_platform_module": { "enabled": false, "mode": "disabled", "supported_modes": [ "disabled", "tpm_2" ] }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "id": "r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } }
Update a bare metal server
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.
PATCH /bare_metal_servers/{id}
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The bare metal server patch
Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the bare metal server will fail to boot.
For
enable_secure_boot
to be changed, the bare metal serverstatus
must bestopped
.The name for this bare metal server. The name must not be used by another bare metal server in the region. Changing the name will not affect the system hostname.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server
curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-bare-metal-server-updated" }'
bareMetalServerPatchModel := &vpcv1.BareMetalServerPatch{ Name: core.StringPtr("my-bare-metal-server-update"), } bareMetalServerPatchModelAsPatch, asPatchErr := bareMetalServerPatchModel.AsPatch() options := &vpcv1.UpdateBareMetalServerOptions{ ID: &bareMetalServerId, BareMetalServerPatch: bareMetalServerPatchModelAsPatch, } bareMetalServer, response, err := vpcService.UpdateBareMetalServer(options)
BareMetalServerPatch bareMetalServerPatchModel = new BareMetalServerPatch.Builder() .name("my-bare-metal-server-updated") .build(); Map<String, Object> bareMetalServerPatchModelAsPatch = bareMetalServerPatchModel.asPatch(); UpdateBareMetalServerOptions updateBareMetalServerOptions = new UpdateBareMetalServerOptions.Builder() .id(bareMetalServerId) .bareMetalServerPatch(bareMetalServerPatchModelAsPatch) .build(); Response<BareMetalServer> response = vpcService.updateBareMetalServer(updateBareMetalServerOptions).execute(); BareMetalServer bareMetalServer = response.getResult();
const params = { id: bareMetalServerId, enableSecureBoot: false, name: 'my-bare-metal-server-updated', }; const response = await vpcService.updateBareMetalServer(params)
bare_metal_server_patch_model = { 'name': 'my-bare-metal-server-updated' } bare_metal_server = service.update_bare_metal_server( id=bare_metal_server_id, bare_metal_server_patch=bare_metal_server_patch_model ).get_result()
Response
The total bandwidth (in megabits per second) shared across the bare metal server network attachments or bare metal server network interfaces
Possible values: 1 ≤ value ≤ 1000000
Example:
20000
The resource from which this bare metal server is booted.
The resources supported by this property may expand in the future.
Examples:ViewThe bare metal server CPU configuration
The date and time that the bare metal server was created
The CRN for this bare metal server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::bare-metal-server:1e09281b-f177-46fb-baf1-bc152b2e391a
The disks for this bare metal server, including any disks that are associated with the
boot_target
.Possible values: number of items ≥ 0
Indicates whether secure boot is enabled. If enabled, the image must support secure boot or the server will fail to boot.
The URL for this bare metal server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this bare metal server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the bare metal server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The amount of memory, truncated to whole gibibytes
Possible values: 1 ≤ value ≤ 100000
Example:
1536
The name for this bare metal server. The name is unique across all bare metal servers in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server
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.
Possible values: number of items ≥ 1
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.
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.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/bare_metal_servers/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e
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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this bare metal server network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-interface
- Examples:View
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_interface
The profile for this bare metal server
The URL for this bare metal server profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/profiles/bx2-metal-192x768
The name for this bare metal server profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-metal-192x768
The resource type
Possible values: [
bare_metal_server_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The resource group for this bare metal server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
bare_metal_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this bare metal server:
deleting
: server is undergoing deletionfailed
: server is failed and not usable (seestatus_reasons
)maintenance
: server is undergoing maintenance (not usable)pending
: server is being provisioned and not yet usablerestarting
: server is restarting and not yet usablerunning
: server is powered onstarting
: server is starting and not yet usablestopped
: server is powered off
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,maintenance
,pending
,restarting
,running
,starting
,stopped
]The reasons for the current status (if any).
Possible values: number of items ≥ 0
The VPC this bare metal server resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this bare metal server resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The network attachments for this bare metal server, including the primary network attachment.
Possible values: number of items ≥ 0
The primary network attachment for this bare metal server.
The URL for this bare metal server network attachment
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The unique identifier for this bare metal server network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6
The name for this bare metal server network attachment. The name is unique across all network attachments for the bare metal server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-bare-metal-server-network-attachment
The primary IP address of the virtual network interface for the bare metal server network attachment
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource type
Possible values: [
bare_metal_server_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the bare metal server network attachment
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_network_attachment
Status Code
The bare metal server was updated successfully.
An invalid bare metal server patch was provided.
The bare metal server is not allowed to be updated.
A bare metal server with the specified identifier could not be found.
The requested update requires that the bare metal server be stopped first.
{ "bandwidth": 100000, "boot_target": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "name": "updated-disk-name", "resource_type": "bare_metal_server_disk" }, "cpu": { "architecture": "amd64", "core_count": 96, "socket_count": 4, "threads_per_core": 2 }, "created_at": "2021-05-21T06:09:15.000Z", "crn": "crn:[...]", "disks": [ { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-3744f199-6ccc-4698-8772-bb3937348c96", "id": "2302-3744f199-6ccc-4698-8772-bb3937348c96", "interface_type": "sata", "name": "updated-disk-name", "resource_type": "bare_metal_server_disk", "size": 960 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-86003aba-47db-4d07-bd76-62e00cca83e5", "id": "2302-86003aba-47db-4d07-bd76-62e00cca83e5", "interface_type": "nvme", "name": "elderly-mountain-trout-opponent", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "id": "2302-8372237f-77cb-47e4-9c61-b9d19ddfdbcd", "interface_type": "nvme", "name": "could-kilt-twisty-unloaded", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-e544d72d-ca08-4924-b748-a8f67b66286d", "id": "2302-e544d72d-ca08-4924-b748-a8f67b66286d", "interface_type": "nvme", "name": "wildcat-impromptu-dribble-hesitate", "resource_type": "bare_metal_server_disk", "size": 3200 }, { "created_at": "2021-05-21T06:09:15.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/disks/2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "id": "2302-de34647b-e7fb-405b-85af-d28c6dfe142c", "interface_type": "nvme", "name": "imperfect-stimulate-culpable-thumb", "resource_type": "bare_metal_server_disk", "size": 3200 } ], "enable_secure_boot": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "id": "2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c", "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 768, "name": "my-bare-metal-server-updated", "network_attachments": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "id": "2302-62c7b99f-a771-4f6b-94a6-788cc0971197", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.12", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/a053a8c6-ed22-4773-8120-4c0c67c8b64a", "id": "a053a8c6-ed22-4773-8120-4c0c67c8b64a", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "network_interfaces": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "id": "2302-8307ea0c-6617-4c3a-bff3-98b17f652e8a", "name": "my-vlan-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.9", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } } ], "primary_network_attachment": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_attachments/2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "id": "2302-da8c43ec-b6ca-4bd2-871e-72e288c66ee6", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.11", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/cacf470c-2e91-47c5-a46d-b2535fba46e4", "id": "cacf470c-2e91-47c5-a46d-b2535fba46e4", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "bare_metal_server_network_attachment", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "primary_network_interface": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_servers/2302-f7a2bf57-af7c-49d9-b599-b2c91293d30c/network_interfaces/2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "id": "2302-63209fe4-0168-4b8f-9618-3e30f7118cdf", "name": "my-primary-network-interface", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "primary_ipv4_address": "10.240.128.7", "resource_type": "network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/bare_metal_server/profiles/bx2d-metal-192x768", "name": "bx2d-metal-192x768", "resource_type": "bare_metal_server_profile" }, "resource_group": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/823edda102129f3232a0dc0655fcff94", "id": "823edda102129f3232a0dc0655fcff94", "name": "Default" }, "resource_type": "bare_metal_server", "status": "running", "status_reasons": [], "trusted_platform_module": { "enabled": false, "mode": "disabled", "supported_modes": [ "disabled", "tpm_2" ] }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "id": "r134-bba5c798-447e-490d-b622-dd4cdd8027f6", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3" } }
Retrieve initialization configuration for a bare metal server
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.
GET /bare_metal_servers/{id}/initialization
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/initialization?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetBareMetalServerInitializationOptions{ ID: &bareMetalServerId, } bareMetalServerInitialization, response, err := vpcService.GetBareMetalServerInitialization(options)
GetBareMetalServerInitializationOptions getBareMetalServerInitializationOptions = new GetBareMetalServerInitializationOptions.Builder() .id(bareMetalServerId) .build(); Response<BareMetalServerInitialization> response = vpcService.getBareMetalServerInitialization(getBareMetalServerInitializationOptions).execute(); BareMetalServerInitialization bareMetalServerInitialization = response.getResult();
const params = { id: bareMetalServerId, }; const response = await vpcService.getBareMetalServerInitialization(params)
bare_metal_server_initialization = service.get_bare_metal_server_initialization( id=bare_metal_server_id).get_result()
Response
The image the bare metal server was provisioned from
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
image
The public SSH keys used at initialization.
The user accounts that are created at initialization. There can be multiple account types distinguished by the
resource_type
property.Possible values: number of items ≥ 0
user_accounts
Status Code
The initialization configuration was retrieved successfully.
A bare metal server with the specified identifier could not be found.
{ "image": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r134-31c8ca90-2623-48d7-8cf7-737be6fc4c3e", "id": "r134-31c8ca90-2623-48d7-8cf7-737be6fc4c3e", "name": "esxi-7", "resource_type": "image" }, "keys": [ { "crn": "crn:[...]", "fingerprint": "SHA256:fK2jte8j2NPDc5dfhFhiH3TqGyPeqv9Fn2IZEpdyqhQ", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/r134-fa0d609a-ced3-45d7-b3e9-e53268e47289", "id": "r134-fa0d609a-ced3-45d7-b3e9-e53268e47289", "name": "my-key" } ], "user_accounts": [ { "encrypted_password": "qQ+/YEApnl1ZtEgIrfprzb065307thTkzlnLqL5ICpesdbBN03dyCQ==", "encryption_key": { "crn": "crn:[...]", "fingerprint": "SHA256:fK2jte8j2NPDc5dfhFhiH3TqGyPeqv9Fn2IZEpdyqhQ", "href": "https://us-south.iaas.cloud.ibm.com/v1/keys/r134-fa0d609a-ced3-45d7-b3e9-e53268e47289", "id": "e36f8405-a255-48da-8ea7-60035e1ae6dd", "name": "my-key" }, "resource_type": "host_user_account", "username": "root" } ] }
Restart a bare metal server
This request restarts a bare metal server. It will run immediately regardless of the state of the server.
POST /bare_metal_servers/{id}/restart
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/restart?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.NewRestartBareMetalServerOptions{ ID: &bareMetalServerId, } response, err := vpcService.RestartBareMetalServer(options)
RestartBareMetalServerOptions restartBareMetalServerOptions = new RestartBareMetalServerOptions.Builder() .id(bareMetalServerId) .build(); Response<Void> response = service.restartBareMetalServer(restartBareMetalServerOptions).execute();
const params = { id: bareMetalServerId, }; const response = await vpcService.restartBareMetalServer(params)
response = service.restart_bare_metal_server( id=bare_metal_server_id).get_result()
Start a bare metal server
This request starts a bare metal server. It will run immediately provided the server is stopped.
POST /bare_metal_servers/{id}/start
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/start?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.NewStartBareMetalServerOptions{ ID: &bareMetalServerId, } response, err := vpcService.StartBareMetalServer(options)
StartBareMetalServerOptions startBareMetalServerOptions = new StartBareMetalServerOptions.Builder() .id(bareMetalServerId) .build(); Response<Void> response = service.startBareMetalServer(startBareMetalServerOptions).execute();
const params = { id: bareMetalServerId, }; const response = await vpcService.startBareMetalServer(params)
response = service.start_bare_metal_server( id=bare_metal_server_id).get_result()
Stop a bare metal server
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.
POST /bare_metal_servers/{id}/stop
Request
Path Parameters
The bare metal server identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Parameters to control the type of stop operation
The type of stop operation:
soft
: signal running operating system to quiesce and shutdown cleanlyhard
: immediately stop the server
Allowable values: [
hard
,soft
]
curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/stop?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "type": "hard" }'
options := &vpcv1.NewStopBareMetalServerOptions{ ID: &bareMetalServerId, Type: &[]string{"hard"}[0], } response, err := vpcService.StopBareMetalServer(options)
StopBareMetalServerOptions stopBareMetalServerOptions = new StopBareMetalServerOptions.Builder() .id(bareMetalServerId) .type("hard") .build(); Response<Void> response = service.stopBareMetalServer(stopBareMetalServerOptions).execute();
const params = { id: bareMetalServerId, type: 'hard', }; const response = await vpcService.stopBareMetalServer(params)
response = service.stop_bare_metal_server( id=bare_metal_server_id, type='hard').get_result()
List all volume profiles
This request lists all volume profiles available in the region. A volume profile specifies the performance characteristics and pricing model for a volume.
GET /volume/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/volume/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVolumeProfilesOptions{} profiles, response, err := vpcService.ListVolumeProfiles(options)
ListVolumeProfilesOptions listVolumeProfilesOptions = new ListVolumeProfilesOptions.Builder() .build(); Response<VolumeProfileCollection> response = service.listVolumeProfiles(listVolumeProfilesOptions).execute(); VolumeProfileCollection volumeProfileCollection = response.getResult();
const response = await vpcService.listVolumeProfiles();
response = service.list_volume_profiles()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of volume profiles
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The volume profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles?limit=50" }, "limit": 50, "profiles": [ { "boot_capacity": { "max": 250, "min": 10, "step": 1, "type": "dependent_range" }, "capacity": { "max": 4800, "min": 10, "step": 1, "type": "dependent_range" }, "family": "tiered", "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/10iops-tier", "iops": { "max": 48000, "min": 100, "step": 1, "type": "dependent_range" }, "name": "10iops-tier", "unattached_capacity_update_supported": { "type": "fixed", "value": false }, "unattached_iops_update_supported": { "type": "fixed", "value": false } }, { "boot_capacity": { "max": 250, "min": 10, "step": 1, "type": "dependent_range" }, "capacity": { "max": 4800, "min": 10, "step": 1, "type": "dependent_range" }, "family": "tiered", "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/5iops-tier", "iops": { "max": 48000, "min": 100, "step": 1, "type": "dependent_range" }, "name": "5iops-tier", "unattached_capacity_update_supported": { "type": "fixed", "value": false }, "unattached_iops_update_supported": { "type": "fixed", "value": false } }, { "boot_capacity": { "max": 250, "min": 10, "step": 1, "type": "dependent_range" }, "capacity": { "max": 4800, "min": 10, "step": 1, "type": "dependent_range" }, "family": "tiered", "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose", "iops": { "max": 48000, "min": 100, "step": 1, "type": "dependent_range" }, "name": "general-purpose", "unattached_capacity_update_supported": { "type": "fixed", "value": false }, "unattached_iops_update_supported": { "type": "fixed", "value": false } }, { "boot_capacity": { "max": 250, "min": 10, "step": 1, "type": "dependent_range" }, "capacity": { "max": 4800, "min": 10, "step": 1, "type": "dependent_range" }, "family": "custom", "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/custom", "iops": { "max": 48000, "min": 100, "step": 1, "type": "dependent_range" }, "name": "custom", "unattached_capacity_update_supported": { "type": "fixed", "value": false }, "unattached_iops_update_supported": { "type": "fixed", "value": false } } ], "total_count": 4 }
Retrieve a volume profile
This request retrieves a single volume profile specified by the name in the URL.
GET /volume/profiles/{name}
Request
Path Parameters
The volume profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/volume/profiles/$profile_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVolumeProfileOptions{} options.SetName(profileName) profile, response, err := vpcService.GetVolumeProfile(options)
GetVolumeProfileOptions getVolumeProfileOptions = new GetVolumeProfileOptions.Builder() .name(volumeProfileName) .build(); Response<VolumeProfile> response = service.getVolumeProfile(getVolumeProfileOptions).execute(); VolumeProfile volumeProfile = response.getResult();
const response = await vpcService.getVolumeProfile({ profileName });
response = service.get_volume_profile(name)
Response
The product family this volume profile belongs to.
The enumerated values for this property may expand in the future.
Possible values: [
custom
,defined_performance
,tiered
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
tiered
The URL for this volume profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
Status Code
The volume profile was retrieved successfully
A volume profile with the specified name could not be found.
{ "boot_capacity": { "max": 250, "min": 10, "step": 1, "type": "dependent_range" }, "capacity": { "max": 16000, "min": 10, "step": 1, "type": "dependent_range" }, "family": "tiered", "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/10iops-tier", "iops": { "max": 48000, "min": 100, "step": 1, "type": "dependent_range" }, "name": "10iops-tier", "unattached_capacity_update_supported": { "type": "fixed", "value": false }, "unattached_iops_update_supported": { "type": "fixed", "value": false } }
List all volumes
This request lists all volumes in the region. Volumes are network-connected block storage devices that may be attached to one or more instances in the same region.
GET /volumes
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to volumes with an
attachment_state
property matching the specified value.Allowable values: [
attached
,unattached
,unusable
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
attached
Filters the collection to resources with an
encryption
property matching the specified value.Allowable values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
Filters the collection to resources with an
operating_system.family
property matching the specified operating system family.This parameter also supports the values
null
andnot:null
which filter the collection to resources which have no operating system or any operating system, respectively.Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
Filters the collection to resources with an
operating_system.architecture
property matching the specified operating system architecture.This parameter also supports the values
null
andnot:null
which filter the collection to resources which have no operating system or any operating system, respectively.Example:
amd64
Filters the collection to resources with a
zone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
Filters the collection to resources with an item in the
tags
property matching the exact specified tag.
curl -X GET "$vpc_api_endpoint/v1/volumes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVolumesOptions{} volumes, response, err := vpcService.ListVolumes(options)
ListVolumesOptions listVolumesOptions = new ListVolumesOptions.Builder() .build(); Response<VolumeCollection> response = service.listVolumes(listVolumesOptions).execute(); VolumeCollection volumeCollection = response.getResult();
const response = await vpcService.listVolumes();
response = service.list_volumes()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
Collection of volumes
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The volumes were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes?limit=50" }, "limit": 50, "total_count": 3, "volumes": [ { "active": true, "attachment_state": "attached", "bandwidth": 128, "busy": false, "capacity": 100, "created_at": "2019-01-29T06:26:17Z", "crn": "crn:[...]", "encryption": "provider_managed", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ccbe6fe1-5680-4865-94d3-687076a38293", "id": "ccbe6fe1-5680-4865-94d3-687076a38293", "iops": 1000, "name": "my-volume-1", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose", "name": "general-purpose" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [ { "delete_volume_on_instance_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/33bd5872-7034-462b-9f3e-d400c49d347a/volume_attachments/b31c1a5a-122a-4e32-a10b-f2c31271de85", "id": "b31c1a5a-122a-4e32-a10b-f2c31271de85", "instance": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/33bd5872-7034-462b-9f3e-d400c49d347a", "id": "33bd5872-7034-462b-9f3e-d400c49d347a", "name": "instance-1" }, "name": "volume-attachment-1", "type": "data" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }, { "active": false, "attachment_state": "unattached", "bandwidth": 128, "busy": false, "capacity": 100, "created_at": "2019-03-23T16:46:54Z", "crn": "crn:[...]", "encryption": "provider_managed", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/9de3e18c-cec9-4cac-a64a-0bdfab21e9d4", "id": "9de3e18c-cec9-4cac-a64a-0bdfab21e9d4", "iops": 1000, "name": "volume-2", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose", "name": "general-purpose" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }, { "active": false, "attachment_state": "unattached", "bandwidth": 128, "busy": false, "capacity": 100, "created_at": "2019-07-13T02:22:43Z", "crn": "crn:[...]", "encryption": "provider_managed", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/89ba05e9-6e35-4964-9747-7ae3f9b30303", "id": "89ba05e9-6e35-4964-9747-7ae3f9b30303", "iops": 1000, "name": "volume-3", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/5iops-tier", "name": "5iops-tier" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2", "resource_type": "zone" } } ] }
Create a volume
This request creates a new volume from a volume prototype object. The prototype object is structured in the same way as a retrieved volume, and contains the information necessary to create the new volume.
POST /volumes
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The volume prototype object
The profile to use for this volume.
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
profile
The zone this volume will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
.Example:
10000
The name for this volume. The name must not be used by another volume in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The resource group to use. If unspecified, the account's default resource group will be used.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Default:
[]
The capacity to use for the volume (in gigabytes). The specified value must be within the
capacity
range of the volume's profile.Example:
100
The root key to use to wrap the data encryption key for the volume.
If unspecified, the
encryption
type for the volume will beprovider_managed
.Examples:View
Any of
curl -X POST "$vpc_api_endpoint/v1/volumes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-volume-4", "iops": 100, "capacity": 50, "zone": { "name": "us-south-2" }, "profile": { "name": "custom" }, "encryption_key":{ "crn":"crn:[...]" }, "resource_group": { "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054" } }'
options := &vpcv1.CreateVolumeOptions{} options.SetVolumePrototype(&vpcv1.VolumePrototype{ Capacity: &capacity, Zone: &vpcv1.ZoneIdentity{ Name: &zoneName, }, Profile: &vpcv1.VolumeProfileIdentity{ Name: &profileName, }, Name: &name, }) volume, response, err := vpcService.CreateVolume(options)
VolumeProfileIdentityByName volumeProfileIdentityModel = new VolumeProfileIdentityByName.Builder() .name("general-purpose") .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); VolumePrototypeVolumeByCapacity volumePrototypeModel = new VolumePrototypeVolumeByCapacity.Builder() .profile(volumeProfileIdentityModel) .zone(zoneIdentityModel) .capacity(Long.valueOf("100")) .name("my-volume") .build(); CreateVolumeOptions createVolumeOptions = new CreateVolumeOptions.Builder() .volumePrototype(volumePrototypeModel) .build(); Response<Volume> response = service.createVolume(createVolumeOptions).execute(); Volume volume = response.getResult();
const volumePrototypeModel = { name: 'my-volume', profile: { name: 'general-purpose' }, zone: { name: zoneName }, capacity: 100, }; const params = { volumePrototype: volumePrototypeModel, }; const response = await vpcService.createVolume(params);
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id volume_profile_identity_model = {} volume_profile_identity_model['name'] = 'general-purpose' zone_identity_model = {} zone_identity_model['name'] = zoneName volume_prototype_model = {} volume_prototype_model['iops'] = 10000 volume_prototype_model['name'] = 'my-volume' volume_prototype_model['profile'] = volume_profile_identity_model volume_prototype_model['resource_group'] = resource_group_identity_model volume_prototype_model['zone'] = zone_identity_model volume_prototype_model['capacity'] = 100 volume_prototype = volume_prototype_model response = service.create_volume(volume_prototype)
Response
Indicates whether a running virtual server instance has an attachment to this volume.
The attachment state of the volume
unattached
: Not attached to any virtual server instancesattached
: Attached to a virtual server instance (even if the instance is stopped)unusable
: Not able to be attached to any virtual server instances
Possible values: [
attached
,unattached
,unusable
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
attached
The maximum bandwidth (in megabits per second) for the volume
Example:
1000
Indicates whether this volume is performing an operation that must be serialized. This must be
false
to perform an operation that is specified to require serialization.The capacity to use for the volume (in gigabytes).
The minimum and maximum limits for this property may expand in the future.
Possible values: value ≥ 1
Example:
1000
The date and time that the volume was created
The CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The type of encryption used on the volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The maximum I/O operations per second (IOPS) for this volume.
Example:
10000
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The profile for this volume.
The URL for this volume profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
profile
The resource group for this volume
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the volume.
The enumerated values for this property may expand in the future.
Possible values: [
available
,failed
,pending
,pending_deletion
,unusable
,updating
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The reasons for the current status (if any).
Possible values: number of items ≥ 0
Indicates whether the capacity for the volume can be changed when not attached to a running virtual server instance.
Indicates whether the IOPS for the volume can be changed when not attached to a running virtual server instance.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The volume attachments for this volume.
The zone this volume resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The root key used to wrap the data encryption key for the volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system associated with this volume. If absent, this volume was not created from an image, or the image did not include an operating system.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The image from which this volume was created (this may be deleted). If absent, this volume was not created from an image.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
The snapshot from which this volume was cloned
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The volume was created successfully
An invalid volume prototype object was provided.
The volume prototype object specified an encryption key that cannot be used in its current state.
{ "active": false, "attachment_state": "unattached", "bandwidth": 128, "busy": false, "capacity": 50, "created_at": "2019-03-28T23:16:53.000Z", "crn": "crn:[...]", "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/2d1bb5a8-40a8-447a-acf7-0eadc8aeb054", "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054", "iops": 100, "name": "my-volume-4", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/custom", "name": "custom" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Delete a volume
This request deletes a volume. This operation cannot be reversed. For this request to succeed, the volume must not be attached to any instances.
DELETE /volumes/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The volume identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/volumes/$volume_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteVolumeOptions{} options.SetID(id) response, err := vpcService.DeleteVolume(options)
DeleteVolumeOptions deleteVolumeOptions = new DeleteVolumeOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteVolume(deleteVolumeOptions).execute();
const response = await vpcService.deleteVolume({ id });
response = service.delete_volume(id)
Retrieve a volume
This request retrieves a single volume specified by the identifier in the URL.
GET /volumes/{id}
Request
Path Parameters
The volume identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/volumes/$volume_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVolumeOptions{} options.SetID(volumeID) volume, response, err := vpcService.GetVolume(options)
GetVolumeOptions getVolumeOptions = new GetVolumeOptions.Builder() .id(id) .build(); Response<Volume> response = service.getVolume(getVolumeOptions).execute(); Volume volume = response.getResult();
const response = await vpcService.getVolume({ id });
response = service.get_volume(id)
Response
Indicates whether a running virtual server instance has an attachment to this volume.
The attachment state of the volume
unattached
: Not attached to any virtual server instancesattached
: Attached to a virtual server instance (even if the instance is stopped)unusable
: Not able to be attached to any virtual server instances
Possible values: [
attached
,unattached
,unusable
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
attached
The maximum bandwidth (in megabits per second) for the volume
Example:
1000
Indicates whether this volume is performing an operation that must be serialized. This must be
false
to perform an operation that is specified to require serialization.The capacity to use for the volume (in gigabytes).
The minimum and maximum limits for this property may expand in the future.
Possible values: value ≥ 1
Example:
1000
The date and time that the volume was created
The CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The type of encryption used on the volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The maximum I/O operations per second (IOPS) for this volume.
Example:
10000
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The profile for this volume.
The URL for this volume profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
profile
The resource group for this volume
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the volume.
The enumerated values for this property may expand in the future.
Possible values: [
available
,failed
,pending
,pending_deletion
,unusable
,updating
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The reasons for the current status (if any).
Possible values: number of items ≥ 0
Indicates whether the capacity for the volume can be changed when not attached to a running virtual server instance.
Indicates whether the IOPS for the volume can be changed when not attached to a running virtual server instance.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The volume attachments for this volume.
The zone this volume resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The root key used to wrap the data encryption key for the volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system associated with this volume. If absent, this volume was not created from an image, or the image did not include an operating system.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The image from which this volume was created (this may be deleted). If absent, this volume was not created from an image.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
The snapshot from which this volume was cloned
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The volume was retrieved successfully
A volume with the specified identifier could not be found.
{ "active": true, "attachment_state": "attached", "bandwidth": 128, "busy": false, "capacity": 100, "created_at": "2019-01-29T06:26:17Z", "crn": "crn:[...]", "encryption": "provider_managed", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/ccbe6fe1-5680-4865-94d3-687076a38293", "id": "ccbe6fe1-5680-4865-94d3-687076a38293", "iops": 1000, "name": "my-volume-1", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose", "name": "general-purpose" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [ { "delete_volume_on_instance_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/33bd5872-7034-462b-9f3e-d400c49d347a/volume_attachments/b31c1a5a-122a-4e32-a10b-f2c31271de85", "id": "b31c1a5a-122a-4e32-a10b-f2c31271de85", "instance": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/33bd5872-7034-462b-9f3e-d400c49d347a", "id": "33bd5872-7034-462b-9f3e-d400c49d347a", "name": "instance-1" }, "name": "volume-attachment-1", "type": "data" } ], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
Update a volume
This request updates a volume with the information in a provided volume patch. The volume patch object is structured in the same way as a retrieved volume and contains only the information to be updated.
PATCH /volumes/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The volume identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The volume patch
The capacity to use for the volume (in gigabytes). For the value to be changed, the volume must be attached to a running virtual server instance, or the
unattached_capacity_update_supported
property must betrue
. Additionally:- The specified value must not be less than the current capacity.
- If the volume is attached as a boot volume, the specified value must not exceed
the
boot_capacity.max
of the volume profile. - If the volume is attached as a data volume, the specified value must not exceed
the
capacity.max
of the volume profile.
Example:
100
The maximum I/O operations per second (IOPS) to use for this volume. Applicable only to volumes using a profile
family
ofcustom
. The volume must be attached as a data volume to a running virtual server instance.Example:
10000
The name for this volume. The name must not be used by another volume in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-volume
The profile to use for this volume. The requested profile must be in the same
family
as the current profile. Additionally:- For the value to be changed on an existing volume, the volume must be attached
to a running virtual server instance, or the volume's
unattached_capacity_update_supported
property must betrue
. - If the volume is a boot volume then the value specified for
capacity
property must not be less than theboot_capacity.min
and must not exceed theboot_capacity.max
of the specified volume profile. - If the volume is a data volume then the value specified for
capacity
property must not be less than thecapacity.min
and must not exceed thecapacity.max
of the specified volume profile.
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
profile
- For the value to be changed on an existing volume, the volume must be attached
to a running virtual server instance, or the volume's
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
curl -X PATCH "$vpc_api_endpoint/v1/volumes/$volume_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-volume-4-update" }'
options := &vpcv1.UpdateVolumeOptions{} options.SetID(id) options.SetName(name) volume, response, err := vpcService.UpdateVolume(options)
UpdateVolumeOptions updateVolumeOptions = new UpdateVolumeOptions.Builder() .id(id) .name(name) .build(); Response<Volume> response = service.updateVolume(updateVolumeOptions).execute(); Volume volume = response.getResult();
const response = await vpcService.updateVolume({ id, name: 'my-volume' });
response = service.update_volume( id, name='my-volume', )
Response
Indicates whether a running virtual server instance has an attachment to this volume.
The attachment state of the volume
unattached
: Not attached to any virtual server instancesattached
: Attached to a virtual server instance (even if the instance is stopped)unusable
: Not able to be attached to any virtual server instances
Possible values: [
attached
,unattached
,unusable
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
attached
The maximum bandwidth (in megabits per second) for the volume
Example:
1000
Indicates whether this volume is performing an operation that must be serialized. This must be
false
to perform an operation that is specified to require serialization.The capacity to use for the volume (in gigabytes).
The minimum and maximum limits for this property may expand in the future.
Possible values: value ≥ 1
Example:
1000
The date and time that the volume was created
The CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The type of encryption used on the volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The maximum I/O operations per second (IOPS) for this volume.
Example:
10000
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The profile for this volume.
The URL for this volume profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/general-purpose
The globally unique name for this volume profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
general-purpose
profile
The resource group for this volume
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the volume.
The enumerated values for this property may expand in the future.
Possible values: [
available
,failed
,pending
,pending_deletion
,unusable
,updating
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The reasons for the current status (if any).
Possible values: number of items ≥ 0
Indicates whether the capacity for the volume can be changed when not attached to a running virtual server instance.
Indicates whether the IOPS for the volume can be changed when not attached to a running virtual server instance.
The user tags associated with this volume.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The volume attachments for this volume.
The zone this volume resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The root key used to wrap the data encryption key for the volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system associated with this volume. If absent, this volume was not created from an image, or the image did not include an operating system.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
The image from which this volume was created (this may be deleted). If absent, this volume was not created from an image.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
The snapshot from which this volume was cloned
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The volume was updated successfully
An invalid volume patch was provided.
A volume with the specified identifier could not be found.
The provided
If-Match
value does not match the current ETag value of the volume
{ "active": false, "attachment_state": "unattached", "bandwidth": 128, "busy": false, "capacity": 50, "created_at": "2019-03-28T23:16:53.000Z", "crn": "crn:[...]", "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/2d1bb5a8-40a8-447a-acf7-0eadc8aeb054", "id": "2d1bb5a8-40a8-447a-acf7-0eadc8aeb054", "iops": 100, "name": "my-volume-4-update", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/volume/profiles/custom", "name": "custom" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "volume", "status": "available", "status_reasons": [], "unattached_capacity_update_supported": false, "unattached_iops_update_supported": false, "user_tags": [], "volume_attachments": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2" } }
List all snapshot consistency groups
This request lists all snapshot consistency groups in the region. A snapshot consistency group is a collection of individual snapshots taken at the same time.
GET /snapshot_consistency_groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to backup policy jobs with a
backup_policy_plan.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
curl -X GET "$vpc_api_endpoint/v1/snapshot_consistency_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSnapshotConsistencyGroupsOptions{} snapshotConsistencyGroups, response, err := vpcService.ListSnapshotConsistencyGroups(options)
ListSnapshotConsistencyGroupsOptions listSnapshotConsistencyGroupsOptions = new ListSnapshotConsistencyGroupsOptions.Builder() .build(); Response<SnapshotConsistencyGroupCollection> response = service.listSnapshotConsistencyGroups(listSnapshotConsistencyGroupsOptions).execute(); SnapshotConsistencyGroupCollection snapshotConsistencyGroupCollectionResult = response.getResult();
const response = await vpcService.listSnapshotConsistencyGroups();
response = vpc_service.list_snapshot_consistency_group()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of snapshot consistency groups
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The snapshot consistency groups were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups?limit=50" }, "limit": 50, "snapshot_consistency_groups": [ { "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "delete_snapshots_on_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "pending", "name": "my-snapshot-consistency-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot_consistency_group", "service_tags": [], "snapshots": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "name": "my-snapshot-1", "resource_type": "snapshot" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-07e34f34-49c2-4763-94fd-c70de73ae342", "id": "r134-07e34f34-49c2-4763-94fd-c70de73ae342", "name": "my-snapshot-2", "resource_type": "snapshot" } ] } ], "total_count": 1 }
Create a snapshot consistency group
This request creates a new snapshot consistency group from a snapshot consistency group object. The prototype object is structured in the same way as a retrieved consistency group, and contains the information necessary to provision the new snapshot consistency group.
POST /snapshot_consistency_groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The snapshot consistency group prototype object
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
Default:
true
The name for this snapshot consistency group. The name must be unique across all snapshot consistency groups in the region.
If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource group to use. If unspecified, the account's default resource group will be used.
The data-consistent member snapshots to create. All snapshots must specify a
source_volume
attached to the same virtual server instance.Possible values: number of items ≥ 1
One of
curl -X POST "$vpc_api_endpoint/v1/snapshot_consistency_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-snapshot", "snapshots": [{"name": "snapshot-name-1>", "source_volume": {"id": "r134-411a798c-5816-4082-8ecb-554a440f83de"} }] }'
snapshotConsistencyGroupPrototypeSnapshotsItem1 := &vpcv1.SnapshotConsistencyGroupPrototypeSnapshotsItem{ Name: core.StringPtr("my-snapshot-1"), SourceVolume: &vpcv1.VolumeIdentityByID{ ID: &volumeID, }, UserTags: []string{"disk:boot"}, } snapshotConsistencyGroupPrototypeSnapshotsItem2 := &vpcv1.SnapshotConsistencyGroupPrototypeSnapshotsItem{ Name: core.StringPtr("my-snapshot-2"), SourceVolume: &vpcv1.VolumeIdentityByID{ ID: &volumeID1, }, UserTags: []string{"disk:system"}, } snapshotConsistencyGroupPrototype := &vpcv1.SnapshotConsistencyGroupPrototype{ DeleteSnapshotsOnDelete: core.BoolPtr(true), Name: core.StringPtr("my-snapshot-consistency-group"), Snapshots: []vpcv1.SnapshotConsistencyGroupPrototypeSnapshotsItem{snapshotConsistencyGroupPrototypeSnapshotsItem1,snapshotConsistencyGroupPrototypeSnapshotsItem2}, } options := &vpcv1.CreateSnapshotConsistencyGroupOptions{ SnapshotConsistencyGroupPrototype: &snapshotConsistencyGroupPrototype } snapshotConsistencyGroup, response, err := vpcService.CreateSnapshotConsistencyGroup(options)
VolumeIdentityById volumeIdentityModel = new VolumeIdentityById.Builder() .id(volumeID) .build(); VolumeIdentityById volumeIdentityModel1 = new VolumeIdentityById.Builder() .id(volumeID1) .build(); SnapshotConsistencyGroupPrototypeSnapshotsItem snapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshotsSnapshotsItemModel1 = new SnapshotConsistencyGroupPrototypeSnapshotsItem.Builder() .name("my-snapshot-1") .sourceVolume(volumeIdentityModel) .userTags(java.util.Arrays.asList("disk:boot")) .build(); SnapshotConsistencyGroupPrototypeSnapshotsItem snapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshotsSnapshotsItemModel2 = new SnapshotConsistencyGroupPrototypeSnapshotsItem.Builder() .name("my-snapshot-2") .sourceVolume(volumeIdentityModel1) .userTags(java.util.Arrays.asList("disk:system")) .build(); SnapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshots snapshotConsistencyGroupPrototypeModel = new SnapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshots.Builder() .deleteSnapshotsOnDelete(true) .name("my-snapshot-consistency-group") .snapshots(java.util.Arrays.asList(snapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshotsSnapshotsItemModel1, snapshotConsistencyGroupPrototypeSnapshotConsistencyGroupBySnapshotsSnapshotsItemModel2)) .build(); CreateSnapshotConsistencyGroupOptions createSnapshotConsistencyGroupOptions = new CreateSnapshotConsistencyGroupOptions.Builder() .snapshotConsistencyGroupPrototype(snapshotConsistencyGroupPrototypeModel) .build(); Response<Snapshot> response = service.createSnapshotConsistencyGroup(createSnapshotConsistencyGroupOptions).execute(); Snapshot snapshotResult = response.getResult();
const snapshotConsistencyGroupBySnapshots1 = { name: 'my-snapshot-1', source_volume: { id: volumeID, }, user_tags: ['disk:boot'], }; const snapshotConsistencyGroupBySnapshots2 = { name: 'my-snapshot-2', source_volume: { id: volumeID1, }, user_tags: ['disk:system'], }; const snapshotConsistencyGroupPrototype = { delete_snapshots_on_delete: false, name: 'my_snapshot-consistency-group', snapshots: [snapshotConsistencyGroupBySnapshots1, snapshotConsistencyGroupBySnapshots2], }; const params = { snapshotConsistencyGroupPrototype: SnapshotConsistencyGroupPrototype }; const response = await vpcService.createSnapshotConsistencyGroup(params);
source_volume_model = {} source_volume_model['id'] = volume_id snapshot_consistency_group_by_snapshots = { 'source_volume' = source_volume_model, 'name': `my-snapshot-1`, 'user_tags': ['disk:boot'], } source_volume_model1 = {} source_volume_model1['id'] = volume_id1 snapshot_consistency_group_by_snapshots1 = { 'source_volume' = source_volume_model1, 'name': `my-snapshot-2`, 'user_tags': ['disk:system'], } snapshot_consistency_group_prototype = { delete_snapshots_on_delete = false, snapshots = [snapshot_consistency_group_by_snapshots, snapshot_consistency_group_by_snapshots1], name = `my_snapshot_consistency_group`, } response = vpc_service.create_snapshot( source_volume=source_volume_model, name='my-snapshot') response = response.get_result()
Response
The date and time that this snapshot consistency group was created
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot consistency group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource group for this snapshot consistency group.
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags associated with this snapshot consistency group. Each tag is prefixed with is.instance:.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The member snapshots that are data-consistent with respect to captured time. (may be deleted).
Possible values: number of items ≥ 1, contains only unique items
If present, the backup policy plan which created this snapshot consistency group.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
Status Code
The snapshot consistency group was created successfully.
An invalid snapshot consistency group prototype object was provided.
{ "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "delete_snapshots_on_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "pending", "name": "my-snapshot-consistency-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot_consistency_group", "service_tags": [], "snapshots": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "name": "my-snapshot-1", "resource_type": "snapshot" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-07e34f34-49c2-4763-94fd-c70de73ae342", "id": "r134-07e34f34-49c2-4763-94fd-c70de73ae342", "name": "my-snapshot-2", "resource_type": "snapshot" } ] }
Delete a snapshot consistency group
This request deletes snapshot consistency group. This operation cannot be reversed. If
the delete_snapshots_on_delete
property is true
, all snapshots in the consistency
group will also be deleted.
DELETE /snapshot_consistency_groups/{id}
Request
Path Parameters
The snapshot consistency group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/snapshot_consistency_groups/$snapshot_consistency_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSnapshotConsistencyGroupOptions{ ID: &snapshotConsistencyGroupID, } response, err := vpcService.DeleteSnapshotConsistencyGroup(options)
DeleteSnapshotConsistencyGroupsOptions deleteSnapshotConsistencyGroupsOptions = new DeleteSnapshotConsistencyGroupsOptions.Builder() .id(snapshotConsistencyGroupID) .build(); Response<Void> response = service.deleteSnapshotConsistencyGroups(deleteSnapshotConsistencyGroupsOptions).execute();
const response = await vpcService.deleteSnapshotConsistencyGroup({ id: snapshotConsistencyGroupID });
response = vpc_service.delete_snapshot_consistency_group(snapshot_consistency_group_id)
Response
The date and time that this snapshot consistency group was created
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot consistency group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource group for this snapshot consistency group.
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags associated with this snapshot consistency group. Each tag is prefixed with is.instance:.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The member snapshots that are data-consistent with respect to captured time. (may be deleted).
Possible values: number of items ≥ 1, contains only unique items
If present, the backup policy plan which created this snapshot consistency group.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
Status Code
The snapshot consistency group deletion request was accepted.
A snapshot consistency group with the specified identifier could not be found.
{ "created_at": "2021-05-18T20:19:12Z", "crn": "crn:[...]", "delete_snapshots_on_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "deleting", "name": "my-snapshot-consistency-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot_consistency_group", "service_tags": [], "snapshots": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "name": "my-snapshot-1", "resource_type": "snapshot" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-07e34f34-49c2-4763-94fd-c70de73ae342", "id": "r134-07e34f34-49c2-4763-94fd-c70de73ae342", "name": "my-snapshot-2", "resource_type": "snapshot" } ] }
Retrieve a snapshot consistency group
This request retrieves a single snapshot consistency group specified by the identifier in the URL.
GET /snapshot_consistency_groups/{id}
Request
Path Parameters
The snapshot consistency group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/snapshot_consistency_groups/$snapshot_consistency_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSnapshotConsistencyGroupOptions{ ID: &snapshotConsistencyGroupID, } snapshotConsistencyGroup, response, err := vpcService.GetSnapshotConsistencyGroup(options) snapshotConsistencyGroupETag = response.Headers.Get("ETag")
GetSnapshotConsistencyGroupOptions getSnapshotConsistencyGroupOptions = new GetSnapshotConsistencyGroupOptions.Builder() .id(snapshotConsistencyGroupID) .build(); Response<SnapshotConsistencyGroup> response = service.getSnapshotConsistencyGroup(getSnapshotConsistencyGroupOptions).execute(); SnapshotConsistencyGroup snapshotConsistencyGroupResult = response.getResult();
const response = await vpcService.getSnapshotConsistencyGroup({ id: snapshotConsistencyGroupID });
response = vpc_service.get_snapshot_consistency_group(snapshot_consistency_group_id) snapshot_consistency_group = response.get_result()
Response
The date and time that this snapshot consistency group was created
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot consistency group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource group for this snapshot consistency group.
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags associated with this snapshot consistency group. Each tag is prefixed with is.instance:.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The member snapshots that are data-consistent with respect to captured time. (may be deleted).
Possible values: number of items ≥ 1, contains only unique items
If present, the backup policy plan which created this snapshot consistency group.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
Status Code
The snapshot consistency group was retrieved successfully
A snapshot consistency group with the specified identifier could not be found.
{ "created_at": "2021-05-18T20:19:12Z", "crn": "crn:[...]", "delete_snapshots_on_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "stable", "name": "my-snapshot-consistency-group", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot_consistency_group", "service_tags": [], "snapshots": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "name": "my-snapshot-1", "resource_type": "snapshot" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-07e34f34-49c2-4763-94fd-c70de73ae342", "id": "r134-07e34f34-49c2-4763-94fd-c70de73ae342", "name": "my-snapshot-2", "resource_type": "snapshot" } ] }
Update a snapshot consistency group
This request updates a snapshot consistency group with the information in a provided snapshot consistency group patch. The snapshot consistency group patch object is structured in the same way as a retrieved snapshot consistency group and contains only the information to be updated.
PATCH /snapshot_consistency_groups/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The snapshot consistency group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The snapshot consistency group patch
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
The name for this snapshot consistency group. The name must not be used by another snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
curl -X PATCH "$vpc_api_endpoint/v1/snapshot_consistency_groups/$snapshot_consistency_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-updated-snapshot-consistency-group" }'
name := "my-snapshot-consistency-group-updated" snapshotConsistencyGroupPatchModel := &vpcv1.SnapshotConsistencyGroupPatch{ Name: &name, } snapshotConsistencyGroupPatch, asPatchErr := snapshotConsistencyGroupPatchModel.AsPatch() options := &vpcv1.UpdateSnapshotConsistencyGroupOptions{ ID: &snapshotID, SnapshotConsistencyGroupPatch: snapshotConsistencyGroupPatch, IfMatch: snapshotConsistencyGroupETag, } snapshotConsistencyGroup, response, err := vpcService.UpdateSnapshotConsistencyGroup(options)
SnapshotConsistencyGroupPatch snapshotConsistencyGroupPatchModel = new SnapshotConsistencyGroupPatch.Builder() .name("my-snapshot-consistency-group-updated") .build(); Map<String, Object> snapshotConsistencyGroupPatchModelAsPatch = snapshotConsistencyGroupPatchModel.asPatch(); UpdateSnapshotConsistencyGroupOptions updateSnapshotConsistencyGroupOptions = new UpdateSnapshotConsistencyGroupOptions.Builder() .id(snapshotConsistencyGroupID) .snapshotConsistencyGroupPatch(snapshotConsistencyGroupPatchModelAsPatch) .build(); Response<Snapshot> response = service.updateSnapshot(updateSnapshotOptions).execute(); Snapshot snapshotResult = response.getResult();
const params = { id: snapshotConsistencyGroupID, name: 'my-snapshot-consistency-group-updated', }; const response = await vpcService.updateSnapshotConsistencyGroup(params);
snapshot_consistency_group_patch_model = {} snapshot_consistency_group_patch_model['name'] = 'my_snapshot_consistency_group-updated' response = vpc_service.update_snapshot_consistency_group( snapshot_consistency_group_id, snapshot_consistency_group_patch=snapshot_consistency_group_patch_model) response = response.get_result()
Response
The date and time that this snapshot consistency group was created
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
Indicates whether deleting the snapshot consistency group will also delete the snapshots in the group.
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot consistency group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource group for this snapshot consistency group.
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags associated with this snapshot consistency group. Each tag is prefixed with is.instance:.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The member snapshots that are data-consistent with respect to captured time. (may be deleted).
Possible values: number of items ≥ 1, contains only unique items
If present, the backup policy plan which created this snapshot consistency group.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
Status Code
The snapshot consistency group was updated successfully.
An invalid snapshot consistency group patch was provided.
A snapshot consistency group with the specified identifier could not be found.
The provided
If-Match
value does not match the current ETag value of the snapshot consistency group
{ "created_at": "2021-05-18T20:19:12Z", "crn": "crn:[...]", "delete_snapshots_on_delete": true, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "stable", "name": "my-snapshot-consistency-group-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot_consistency_group", "service_tags": [], "snapshots": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "name": "my-snapshot-1", "resource_type": "snapshot" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-07e34f34-49c2-4763-94fd-c70de73ae342", "id": "r134-07e34f34-49c2-4763-94fd-c70de73ae342", "name": "my-snapshot-2", "resource_type": "snapshot" } ] }
Delete a filtered collection of snapshots
This request deletes all snapshots created from a specific source volume
DELETE /snapshots
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
source_volume.id
property matching the specified identifier.
curl -X DELETE "$vpc_api_endpoint/v1/snapshots?source_volume.id=r134-411a798c-5816-4082-8ecb-554a440f83de&version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSnapshotsOptions{ SourceVolumeID: &volumeID, } response, err := vpcService.DeleteSnapshots(options)
DeleteSnapshotsOptions deleteSnapshotsOptions = new DeleteSnapshotsOptions.Builder() .sourceVolumeId(volumeID) .build(); Response<Void> response = service.deleteSnapshots(deleteSnapshotsOptions).execute();
const response = await vpcService.deleteSnapshots({ sourceVolumeId: volumeID });
response = vpc_service.delete_snapshots( source_volume_id)
List all snapshots
This request lists all snapshots in the region. A snapshot preserves the data of a volume at the time the snapshot is created.
GET /snapshots
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with an item in the
tags
property matching the exact specified tag.Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
source_volume.id
property matching the specified identifier.Filters the collection to resources with a
source_volume.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:1a6b7274-678d-4dfb-8981-c71dd9d4daa5
Filters the collection to resources with a
source_image.id
property matching the specified identifier.This parameter also supports the values
null
andnot:null
which filter the collection to resources which have no source image or any existent source image, respectively.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
source_image.crn
property matching the specified CRN.This parameter also supports the values
null
andnot:null
which filter the collection to resources which have no source image or any existent source image, respectively.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to backup policy jobs with a
backup_policy_plan.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to snapshots with an item in the
copies
property with anid
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to snapshots with an item in the
copies
property with aname
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-copy
Filters the collection to snapshots with an item in the
copies
property with anid
property matching the specified CRN.Filters the collection to snapshots with an item in the
copies
property with aremote.region.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
Filters the collection to resources with a
source_snapshot.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
source_snapshot.remote.region.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
Filters the collection to resources with a
source_volume.remote.region.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
Filters the collection to resources with a
source_image.remote.region.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
Filters the collection to snapshots with an item in the
clones
property with azone.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
Filters the collection to resources with a
snapshot_consistency_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
snapshot_consistency_group.crn
property matching the specified identifier.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
curl -X GET "$vpc_api_endpoint/v1/snapshots?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSnapshotsOptions{} snapshots, response, err := vpcService.ListSnapshots(options)
ListSnapshotsOptions listSnapshotsOptions = new ListSnapshotsOptions.Builder() .build(); Response<SnapshotCollection> response = service.listSnapshots(listSnapshotsOptions).execute(); SnapshotCollection snapshotCollectionResult = response.getResult();
const response = await vpcService.listSnapshots();
response = vpc_service.list_snapshots()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of snapshots
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The snapshots were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots?limit=50" }, "limit": 50, "snapshots": [ { "bootable": true, "clones": [], "copies": [], "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "deletable": true, "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "pending", "minimum_capacity": 100, "name": "my-snapshot", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (amd64)", "family": "Ubuntu Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-20-04-amd64", "name": "ubuntu-20-04-amd64", "user_data_format": "cloud_init", "vendor": "Canonical", "version": "20.04 LTS Focal Fossa Minimal Install" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot", "service_tags": [], "size": 1, "source_image": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "id": "r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "name": "ibm-ubuntu-20-04-minimal-amd64-1", "resource_type": "image" }, "source_volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-411a798c-5816-4082-8ecb-554a440f83de", "id": "r134-411a798c-5816-4082-8ecb-554a440f83de", "name": "my-instance-data", "resource_type": "volume" }, "user_tags": [] } ], "total_count": 1 }
Create a snapshot
This request creates a new snapshot from a snapshot prototype object. The prototype object is structured in the same way as a retrieved snapshot, and contains the information necessary to provision the new snapshot.
POST /snapshots
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The snapshot prototype object
Clones to create for this snapshot
Possible values: contains only unique items
The name for this snapshot. The name must not be used by another snapshot in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource group to use. If unspecified, the account's default resource group will be used.
The user tags associated with this snapshot.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Default:
[]
The volume to create this snapshot from.
One of
curl -X POST "$vpc_api_endpoint/v1/snapshots?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-snapshot", "source_volume": { "id": "r134-411a798c-5816-4082-8ecb-554a440f83de" } }'
name := "my-snapshot" options := &vpcv1.CreateSnapshotOptions{ Name: &name, SourceVolume: &vpcv1.VolumeIdentityByID{ ID: &volumeID, }, } snapshot, response, err := vpcService.CreateSnapshot(options)
VolumeIdentityById volumeIdentityModel = new VolumeIdentityById.Builder() .id(volumeID) .build(); CreateSnapshotOptions createSnapshotOptions = new CreateSnapshotOptions.Builder() .name("my-snapshot") .sourceVolume(volumeIdentityModel) .build(); Response<Snapshot> response = service.createSnapshot(createSnapshotOptions).execute(); Snapshot snapshotResult = response.getResult();
const params = { sourceVolume: { id: volumeID, }, name: 'my-snapshot', }; const response = await vpcService.createSnapshot(params);
source_volume_model = {} source_volume_model['id'] = volume_id create_snapshot_response = vpc_service.create_snapshot( source_volume=source_volume_model, name='my-snapshot') response = create_snapshot_response.get_result()
Response
Indicates if a boot volume attachment can be created with a volume created from this snapshot.
Clones for this snapshot
The copies of this snapshot.
The CRN for the copied snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the copied snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the copied snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the copied snapshot.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
copies
The date and time that this snapshot was created
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
Indicates whether this snapshot can be deleted. This value will always be
true
.The type of encryption used on the source volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The minimum capacity of a volume created from this snapshot. When a snapshot is created, this will be set to the capacity of the
source_volume
.Possible values: value ≥ 1
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource group for this snapshot
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags prefixed with
is.snapshot:
associated with this snapshot.Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The size of this snapshot rounded up to the next gigabyte
Possible values: value ≥ 1
The source volume this snapshot was created from (may be deleted).
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
The user tags associated with this snapshot.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
If present, the backup policy plan which created this snapshot.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
The date and time the data capture for this snapshot was completed.
If absent, this snapshot's data has not yet been captured. Additionally, this property may be absent for snapshots created before 1 January 2022.
The root key used to wrap the data encryption key for the source volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system included in this snapshot.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
If present, the snapshot consistency group which created this snapshot.
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
snapshot_consistency_group
If present, the image from which the data on this snapshot was most directly provisioned.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
If present, the source snapshot this snapshot was created from.
The CRN of the source snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the source snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the source snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the source snapshot. The name is unique across all snapshots in the source snapshot's native region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The snapshot was created successfully.
An invalid snapshot prototype object was provided.
The snapshot prototype object specified one or more of:
- An encryption key that cannot be used in its current state.
- A snapshot that is already the source of another snapshot in this region.
{ "bootable": true, "clones": [], "copies": [], "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "deletable": true, "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "pending", "minimum_capacity": 100, "name": "my-snapshot", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (amd64)", "family": "Ubuntu Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-20-04-amd64", "name": "ubuntu-20-04-amd64", "user_data_format": "cloud_init", "vendor": "Canonical", "version": "20.04 LTS Focal Fossa Minimal Install" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot", "service_tags": [], "size": 1, "source_image": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "id": "r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "name": "ibm-ubuntu-20-04-minimal-amd64-1", "resource_type": "image" }, "source_volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-411a798c-5816-4082-8ecb-554a440f83de", "id": "r134-411a798c-5816-4082-8ecb-554a440f83de", "name": "my-instance-data", "resource_type": "volume" }, "user_tags": [] }
Delete a snapshot
This request deletes a snapshot. This operation cannot be reversed.
DELETE /snapshots/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The snapshot identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/snapshots/$snapshot_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSnapshotOptions{ ID: &snapshotID, } response, err := vpcService.DeleteSnapshot(options)
DeleteSnapshotOptions deleteSnapshotOptions = new DeleteSnapshotOptions.Builder() .id(snapshotID) .build(); Response<Void> response = service.deleteSnapshot(deleteSnapshotOptions).execute();
const response = await vpcService.deleteSnapshot({ id: snapshotID });
response = vpc_service.delete_snapshot(snapshot_id)
Retrieve a snapshot
This request retrieves a single snapshot specified by the identifier in the URL.
GET /snapshots/{id}
Request
Path Parameters
The snapshot identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/snapshots/$snapshot_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSnapshotOptions{ ID: &snapshotID, } snapshot, response, err := vpcService.GetSnapshot(options)
GetSnapshotOptions getSnapshotOptions = new GetSnapshotOptions.Builder() .id(snapshotID) .build(); Response<Snapshot> response = service.getSnapshot(getSnapshotOptions).execute(); Snapshot snapshotResult = response.getResult();
const response = await vpcService.getSnapshot({ id: snapshotID });
response = vpc_service.get_snapshot(snapshot_id) snapshot = get_snapshot_response.get_result()
Response
Indicates if a boot volume attachment can be created with a volume created from this snapshot.
Clones for this snapshot
The copies of this snapshot.
The CRN for the copied snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the copied snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the copied snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the copied snapshot.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
copies
The date and time that this snapshot was created
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
Indicates whether this snapshot can be deleted. This value will always be
true
.The type of encryption used on the source volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The minimum capacity of a volume created from this snapshot. When a snapshot is created, this will be set to the capacity of the
source_volume
.Possible values: value ≥ 1
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource group for this snapshot
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags prefixed with
is.snapshot:
associated with this snapshot.Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The size of this snapshot rounded up to the next gigabyte
Possible values: value ≥ 1
The source volume this snapshot was created from (may be deleted).
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
The user tags associated with this snapshot.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
If present, the backup policy plan which created this snapshot.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
The date and time the data capture for this snapshot was completed.
If absent, this snapshot's data has not yet been captured. Additionally, this property may be absent for snapshots created before 1 January 2022.
The root key used to wrap the data encryption key for the source volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system included in this snapshot.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
If present, the snapshot consistency group which created this snapshot.
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
snapshot_consistency_group
If present, the image from which the data on this snapshot was most directly provisioned.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
If present, the source snapshot this snapshot was created from.
The CRN of the source snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the source snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the source snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the source snapshot. The name is unique across all snapshots in the source snapshot's native region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The snapshot was retrieved successfully
A snapshot with the specified identifier could not be found.
{ "bootable": true, "captured_at": "2021-05-18T20:19:12Z", "clones": [], "copies": [], "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "deletable": true, "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "stable", "minimum_capacity": 100, "name": "my-snapshot", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (amd64)", "family": "Ubuntu Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-20-04-amd64", "name": "ubuntu-20-04-amd64", "user_data_format": "cloud_init", "vendor": "Canonical", "version": "20.04 LTS Focal Fossa Minimal Install" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot", "service_tags": [], "size": 1, "source_image": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "id": "r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "name": "ibm-ubuntu-20-04-minimal-amd64-1", "resource_type": "image" }, "source_volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-411a798c-5816-4082-8ecb-554a440f83de", "id": "r134-411a798c-5816-4082-8ecb-554a440f83de", "name": "my-instance-data", "resource_type": "volume" }, "user_tags": [] }
Update a snapshot
This request updates a snapshot with the information in a provided snapshot patch. The snapshot consistency group patch object is structured in the same way as a retrieved snapshot and contains only the information to be updated.
PATCH /snapshots/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The snapshot identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The snapshot patch
The name for this snapshot. The name must not be used by another snapshot in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The user tags associated with this snapshot.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
curl -X PATCH "$vpc_api_endpoint/v1/snapshots/$snapshot_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-snapshot-updated" }'
name := "my-snapshot-updated" snapshotPatchModel := &vpcv1.SnapshotPatch{ Name: &name, } snapshotPatchModelAsPatch, asPatchErr := snapshotPatchModel.AsPatch() options := &vpcv1.UpdateSnapshotOptions{ ID: &snapshotID, SnapshotPatch: snapshotPatchModelAsPatch, } snapshot, response, err := vpcService.UpdateSnapshot(options)
SnapshotPatch snapshotPatchModel = new SnapshotPatch.Builder() .name("my-snapshot-updated") .build(); Map<String, Object> snapshotPatchModelAsPatch = snapshotPatchModel.asPatch(); UpdateSnapshotOptions updateSnapshotOptions = new UpdateSnapshotOptions.Builder() .id(snapshotID) .snapshotPatch(snapshotPatchModelAsPatch) .build(); Response<Snapshot> response = service.updateSnapshot(updateSnapshotOptions).execute(); Snapshot snapshotResult = response.getResult();
const params = { id: snapshotID, name: 'my-snapshot-updated', }; const response = await vpcService.updateSnapshot(params);
snapshot_patch_model = {} snapshot_patch_model['name'] = 'my-snapshot-updated' update_snapshot_response = vpc_service.update_snapshot( snapshot_id, snapshot_patch=snapshot_patch_model) response = update_snapshot_response.get_result()
Response
Indicates if a boot volume attachment can be created with a volume created from this snapshot.
Clones for this snapshot
The copies of this snapshot.
The CRN for the copied snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the copied snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the copied snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the copied snapshot.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
copies
The date and time that this snapshot was created
The CRN of this snapshot
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
Indicates whether this snapshot can be deleted. This value will always be
true
.The type of encryption used on the source volume
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this snapshot
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The lifecycle state of this snapshot
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The minimum capacity of a volume created from this snapshot. When a snapshot is created, this will be set to the capacity of the
source_volume
.Possible values: value ≥ 1
The name for this snapshot. The name is unique across all snapshots in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource group for this snapshot
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The service tags prefixed with
is.snapshot:
associated with this snapshot.Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The size of this snapshot rounded up to the next gigabyte
Possible values: value ≥ 1
The source volume this snapshot was created from (may be deleted).
Examples:ViewThe CRN for this volume
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The URL for this volume
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/volumes/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/volumes/r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_volume
The user tags associated with this snapshot.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
If present, the backup policy plan which created this snapshot.
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
The date and time the data capture for this snapshot was completed.
If absent, this snapshot's data has not yet been captured. Additionally, this property may be absent for snapshots created before 1 January 2022.
The root key used to wrap the data encryption key for the source volume.
This property will be present for volumes with an
encryption
type ofuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The operating system included in this snapshot.
Users may create new images with this operating system
Example:
true
The operating system architecture
Example:
amd64
Images with this operating system can only be used on dedicated hosts or dedicated host groups
A unique, display-friendly name for the operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server 16.04 LTS amd64
The software family for this operating system
Possible values: 1 ≤ length ≤ 120, Value must match regular expression
^[-A-Za-z0-9 !$@#%&*'=_+:;,?\./\(\)\[\]]+$
Example:
Ubuntu Server
The URL for this operating system
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-amd64
The globally unique name for this operating system
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
ubuntu-16-amd64
The user data format for this operating system:
cloud_init
:user_data
will be interpreted according to the cloud-init standardesxi_kickstart
:user_data
will be interpreted as a VMware ESXi installation scriptipxe
:user_data
will be interpreted as a single URL to an iPXE script or as the text of an iPXE script
Possible values: [
cloud_init
,esxi_kickstart
,ipxe
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The vendor of the operating system
Example:
Canonical
The major release version of this operating system
Example:
16.04 LTS
operating_system
If present, the snapshot consistency group which created this snapshot.
The CRN of this snapshot consistency group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot-consistency-group:r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The URL for this snapshot consistency group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshot_consistency_groups/r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The unique identifier for this snapshot consistency group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fa329f6b-0e36-433f-a3bb-0df632e79263
The name for this snapshot consistency group. The name is unique across all snapshot consistency groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot-consistency-group
The resource type
Possible values: [
snapshot_consistency_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
snapshot_consistency_group
If present, the image from which the data on this snapshot was most directly provisioned.
Examples:ViewThe CRN for this image
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The URL for this image
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/images/r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_image
If present, the source snapshot this snapshot was created from.
The CRN of the source snapshot.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The URL for the source snapshot.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The unique identifier for the source snapshot.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-f6bfa329-0e36-433f-a3bb-0df632e79263
The name for the source snapshot. The name is unique across all snapshots in the source snapshot's native region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-snapshot
The resource type
Possible values: [
snapshot
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_snapshot
Status Code
The snapshot was updated successfully.
An invalid snapshot patch was provided.
A snapshot with the specified identifier could not be found.
The provided
If-Match
value does not match the current ETag value of the snapshot
{ "bootable": true, "captured_at": "2021-05-18T20:19:12Z", "clones": [], "copies": [], "created_at": "2021-05-18T20:18:18Z", "crn": "crn:[...]", "deletable": true, "encryption": "user_managed", "encryption_key": { "crn": "crn:[...]" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "id": "r134-f6bfa329-0e36-433f-a3bb-0df632e79263", "lifecycle_state": "stable", "minimum_capacity": 100, "name": "my-snapshot-updated", "operating_system": { "allow_user_image_creation": true, "architecture": "amd64", "dedicated_host_only": false, "display_name": "Ubuntu Linux 20.04 LTS Focal Fossa Minimal Install (amd64)", "family": "Ubuntu Linux", "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-20-04-amd64", "name": "ubuntu-20-04-amd64", "user_data_format": "cloud_init", "vendor": "Canonical", "version": "20.04 LTS Focal Fossa Minimal Install" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "snapshot", "service_tags": [], "size": 1, "source_image": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "id": "r134-32045dc2-b463-4cda-b424-bc3dcf51dfbb", "name": "ibm-ubuntu-20-04-minimal-amd64-1", "resource_type": "image" }, "source_volume": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-411a798c-5816-4082-8ecb-554a440f83de", "id": "r134-411a798c-5816-4082-8ecb-554a440f83de", "name": "my-instance-data", "resource_type": "volume" }, "user_tags": [] }
List all clones for a snapshot
This request lists all clones for a snapshot. Use a clone to quickly restore a snapshot within the clone's zone.
GET /snapshots/{id}/clones
Request
Path Parameters
The snapshot identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/snapshots/$snapshot_id/clones?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSnapshotClonesOptions{ ID: &snapshotID, } clones, response, err := vpcService.ListSnapshotClones(options)
ListSnapshotClonesOptions listSnapshotClonesOptions = new ListSnapshotClonesOptions.Builder() .id(snapshotID) .build(); Response<SnapshotCloneCollection> response = service.listSnapshotClones(listSnapshotClonesOptions).execute(); SnapshotCloneCollection snapshotCloneCollection = response.getResult();
const response = await vpcService.listSnapshotClones({ id: snapshotID });
response = vpc_service.list_snapshot_clones(snapshot_id) clones = response.get_result()['clones']
Response
Collection of snapshot clones
Status Code
The snapshot clones were retrieved successfully.
A snapshot with the specified identifier could not be found.
{ "clones": [ { "available": true, "created_at": "2022-12-01T06:29:32.000Z", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ] }
Delete a snapshot clone
This request deletes a snapshot clone. This operation cannot be reversed, but an equivalent clone may be recreated from the snapshot.
DELETE /snapshots/{id}/clones/{zone_name}
Request
Path Parameters
The snapshot identifier
The zone name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/snapshots/$snapshot_id/clones/$zone_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSnapshotCloneOptions{ ID: &snapshotID, ZoneName: &zoneName, } response, err := vpcService.DeleteSnapshotClone(options)
DeleteSnapshotCloneOptions deleteSnapshotCloneOptions = new DeleteSnapshotCloneOptions.Builder() .id(snapshotID) .zoneName(zoneName) .build(); Response<Void> response = service.deleteSnapshotClone(deleteSnapshotCloneOptions).execute();
const response = await vpcService.deleteSnapshotClone({ id: snapshotID, zoneName: zoneName });
response = vpc_service.delete_snapshot_clone(snapshot_id, zone_name)
Retrieve a snapshot clone
This request retrieves a single clone specified by the snapshot identifier and zone name in the URL.
GET /snapshots/{id}/clones/{zone_name}
Request
Path Parameters
The snapshot identifier
The zone name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/snapshots/$snapshot_id/clones/$zone_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSnapshotCloneOptions{ ID: &snapshotID, ZoneName: &zoneName, } clone, response, err := vpcService.GetSnapshotClone(options)
GetSnapshotCloneOptions getSnapshotCloneOptions = new GetSnapshotCloneOptions.Builder() .id(snapshotID) .zoneName(zoneName) .build(); Response<SnapshotClone> response = service.getSnapshotClone(getSnapshotCloneOptions).execute(); SnapshotClone snapshotClone = response.getResult();
const response = await vpcService.getSnapshotClone({ id: snapshotID, zoneName: zoneName });
response = vpc_service.get_snapshot_clone(snapshot_id, zone_name) clone = response.get_result()
Response
Indicates whether this snapshot clone is available for use.
The date and time that this snapshot clone was created.
The zone this snapshot clone resides in.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The snapshot clone was retrieved successfully.
A snapshot clone with the specified identifier could not be found.
{ "available": true, "created_at": "2022-12-01T06:29:32.000Z", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Create a clone for a snapshot
This request creates a new clone for a snapshot in the specified zone. A request body is not required, and if provided, is ignored. If the snapshot already has a clone in the zone, it is returned.
PUT /snapshots/{id}/clones/{zone_name}
Request
Path Parameters
The snapshot identifier
The zone name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/snapshots/$snapshot_id/clones/$zone_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.CreateSnapshotCloneOptions{ ID: &snapshotID, ZoneName: &zoneName, } clone, response, err := vpcService.CreateSnapshotClone(options)
CreateSnapshotCloneOptions createSnapshotCloneOptions = new CreateSnapshotCloneOptions.Builder() .id(snapshotID) .zoneName(zoneName) .build(); Response<SnapshotClone> response = service.createSnapshotClone(createSnapshotCloneOptions).execute(); SnapshotClone snapshotClone = response.getResult();
const params = { id: snapshotID, zoneName: zoneName, }; const response = await vpcService.createSnapshotClone(params);
create_snapshot_clone_response = vpc_service.create_snapshot_clone( snapshot_id, zone_name) response = create_snapshot_clone_response.get_result()
Response
Indicates whether this snapshot clone is available for use.
The date and time that this snapshot clone was created.
The zone this snapshot clone resides in.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The snapshot clone was retrieved successfully.
The snapshot clone was created successfully.
A snapshot or zone with the specified identifier could not be found.
{ "available": true, "created_at": "2022-12-01T06:29:32.000Z", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
{ "available": false, "created_at": "2022-12-01T06:29:32.000Z", "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all file share profiles
This request lists all file share profiles available in the region. A file share profile specifies the performance characteristics and pricing model for a file share.
GET /share/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
curl -X GET "$vpc_api_endpoint/v1/share/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listShareProfilesOptions := &vpcv1.ListShareProfilesOptions{} shareProfileCollection, response, err := vpcService.ListShareProfiles(listShareProfilesOptions)
ListShareProfilesOptions listShareProfilesOptions = new ListShareProfilesOptions.Builder() .build(); Response<ShareProfileCollection> response = vpcService.listShareProfiles(listShareProfilesOptions).execute(); ShareProfileCollection shareProfileCollectionResult = response.getResult();
const response = await vpcService.listShareProfiles();
response = vpc_service.list_share_profiles() share_profile_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of share profiles
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The share profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles?limit=50" }, "limit": 50, "profiles": [ { "capacity": { "max": 32000, "min": 10, "step": 1, "type": "dependent_range" }, "family": "defined_performance", "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/dp2", "iops": { "default": 100, "max": 96000, "min": 100, "step": 1, "type": "range" }, "name": "dp2", "resource_type": "share_profile" } ], "total_count": 1 }
Retrieve a file share profile
This request retrieves a single file share profile specified by the name in the URL.
GET /share/profiles/{name}
Request
Path Parameters
The file share profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/share/profiles/$name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getShareProfileOptions := &vpcv1.GetShareProfileOptions{ Name: &[]string{"dp2"}[0], } shareProfile, response, err := vpcService.GetShareProfile(getShareProfileOptions)
GetShareProfileOptions getShareProfileOptions = new GetShareProfileOptions.Builder() .name("dp2") .build(); Response<ShareProfile> response = vpcService.getShareProfile(getShareProfileOptions).execute(); ShareProfile shareProfile = response.getResult();
const params = { name: 'dp2', }; const response = await vpcService.getShareProfile(params);
response = vpc_service.get_share_profile( name='dp2', ) share_profile = response.get_result()
Response
The permitted capacity range (in gigabytes) for a share with this profile
The type for this profile field
Possible values: [
fixed
]The value for this profile field
Example:
4800
capacity
The product family this share profile belongs to.
Possible values: [
custom
,defined_performance
,tiered
]Example:
defined_performance
The URL for this share profile.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops
The permitted IOPS range for a share with this profile
The type for this profile field
Possible values: [
fixed
]The value for this profile field
Example:
4000
iops
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
The resource type
Possible values: [
share_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The share profile was retrieved successfully
A file share profile with the specified name could not be found.
{ "capacity": { "max": 32000, "min": 10, "step": 1, "type": "dependent_range" }, "family": "defined_performance", "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/dp2", "iops": { "default": 100, "max": 96000, "min": 100, "step": 1, "type": "range" }, "name": "dp2", "resource_type": "share_profile" }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to file shares with a
replication_role
property matching the specified value.Allowable values: [
none
,replica
,source
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/shares?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listSharesOptions := &vpcv1.ListSharesOptions{} shareCollection, response, err := vpcService.ListShares(listSharesOptions)
ListSharesOptions listSharesOptions = new ListSharesOptions.Builder() .build(); Response<ShareCollection> response = vpcService.listShares(listSharesOptions).execute(); ShareCollection shareCollectionResult = response.getResult();
const response = await vpcService.listShares();
response = vpc_service.list_shares() share_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of file shares
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The file shares were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86?limit=50" }, "limit": 50, "shares": [ { "access_control_mode": "security_group", "created_at": "2021-04-24T22:58:49.000Z", "crn": "crn:[...]", "encryption": "provider_managed", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "iops": 14400, "lifecycle_state": "stable", "mount_targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "name": "my-share-mount-target", "resource_type": "share_mount_target", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc" } } ], "name": "my-share", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops", "name": "tier-3iops", "resource_type": "share_profile" }, "replication_role": "none", "replication_status": "none", "replication_status_reasons": [], "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "share", "size": 4800, "user_tags": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "total_count": 1 }
Create a file share
This request provisions new file shares from a share prototype object. The new file shares can be a standalone share, a replica share, or both a source and replica share.
The prototype object is structured in the same way as a retrieved share, and contains the information necessary to provision the new file shares.
POST /shares
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The file share prototype object
The profile to use for this file share. The profile must support the share's specified IOPS and size.
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
profile
The zone this file share will reside in. For a replica share, this must be a different zone in the same region as the source share.
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The maximum input/output operations per second (IOPS) for the file share. The share must be in the
custom
ordefined_performance
profile family, and the value must be in the range supported by the share's specified size.In addition, each client accessing the share will be restricted to 48,000 IOPS.
Possible values: 100 ≤ value ≤ 96000
Example:
100
The mount targets for the file share. Each mount target must be in a unique VPC.
mount_targets
The name for this share. The name must not be used by another share in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
Configuration for a replica file share to create and associate with this file share. If unspecified, a replica may be subsequently added by creating a new file share with a
source_share
referencing this file share.Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Default:
[]
Create a file share by size.
The size of the file share rounded up to the next gigabyte.
The maximum size for a share may increase in the future.
Possible values: 10 ≤ value ≤ 32000
Example:
200
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target. Mount targets for this share require a virtual network interface.vpc
: All clients in the VPC for a mount target have access to the mount target. Mount targets for this share require a VPC.
Allowable values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
security_group
The root key to use to wrap the data encryption key for the share.
If unspecified, the
encryption
type for the share will beprovider_managed
.The specified key may be in a different account, subject to IAM policies.
Examples:ViewThe owner assigned to the file share at creation. Subsequent changes to the owner must be performed by a client that has mounted the file share.
The initial group identifier for the file share.
Possible values: 0 ≤ value ≤ 2147483647
Default:
0
Example:
50
The initial user identifier for the file share.
Possible values: 0 ≤ value ≤ 2147483647
Default:
0
Example:
50
initial_owner
One of
curl -X POST "$vpc_api_endpoint/v1/shares?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-share", "profile": { "name": "tier-3iops" }, "zone": { "name": "us-south-1" }, "size": 4800, "mount_targets": [ { "name": "my-target", "vpc": { "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084" } } ] }'
shareProfileIdentityModel := &vpcv1.ShareProfileIdentityByName{ Name: &[]string{"dp2"}[0], } zoneIdentityModel := &vpcv1.ZoneIdentityByName{ Name: &zoneName, } sharePrototypeModel := &vpcv1.SharePrototypeShareBySize{ Iops: &[]int64{100}[0], Name: &[]string{"my-share"}[0], Profile: shareProfileIdentityModel, UserTags: []string{"my-share-tag"}, Zone: zoneIdentityModel, AccessControlMode: &[]string{"security_group"}[0], Size: &[]int64{200}[0], } createShareOptions := &vpcv1.CreateShareOptions{ SharePrototype: sharePrototypeModel, } share, response, err := vpcService.CreateShare(createShareOptions)
ShareProfileIdentityByName shareProfileIdentityModel = new ShareProfileIdentityByName.Builder() .name("dp2") .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); SharePrototypeShareBySize sharePrototypeModel = new SharePrototypeShareBySize.Builder() .iops(Long.valueOf("100")) .name("my-share") .profile(shareProfileIdentityModel) .userTags(java.util.Arrays.asList("my-share-tag")) .zone(zoneIdentityModel) .accessControlMode("security_group") .size(Long.valueOf("200")) .build(); CreateShareOptions createShareOptions = new CreateShareOptions.Builder() .sharePrototype(sharePrototypeModel) .build(); Response<Share> response = vpcService.createShare(createShareOptions).execute(); Share share = response.getResult();
const shareProfileIdentityModel = { name: 'dp2', }; const zoneIdentityModel = { name: zoneName, }; const sharePrototypeModel = { iops: 100, name: 'my-share', profile: shareProfileIdentityModel, user_tags: ['my-share-tag'], zone: zoneIdentityModel, access_control_mode: 'security_group', size: 200, }; const params = { sharePrototype: sharePrototypeModel, }; const response = await vpcService.createShare(params);
share_profile_identity_model = { 'name': 'dp2', } zone_identity_model = { 'name': zoneName, } share_prototype_model = { 'profile': share_profile_identity_model, 'zone': zone_identity_model, 'name': 'my-share', 'size': 200, 'access_control_mode': 'security_group', } response = vpc_service.create_share( share_prototype=share_prototype_model, ) share = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the file share is created
The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The type of encryption used for this file share
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The maximum input/output operations per second (IOPS) for the file share. In addition, each client accessing the share will be restricted to 48,000 IOPS.
The maximum IOPS for a share may increase in the future.
Possible values: 100 ≤ value ≤ 96000
Example:
100
The lifecycle state of the file share
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The mount targets for the file share
Possible values: number of items ≥ 0
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The profile for this file share
The URL for this share profile.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
The resource type
Possible values: [
share_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The replication role of the file share:
none
: This share is not participating in replication.replica
: This share is a replication target.source
: This share is a replication source.
The enumerated values for this property may expand in the future.
Possible values: [
none
,replica
,source
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The replication status of the file share:
active
: This share is actively participating in replication, and the replica's data is up-to-date with the replication schedule.degraded
: This is share is participating in replication, but the replica's data has fallen behind the replication schedule.failover_pending
: This share is performing a replication failover.initializing
: This share is initializing replication.none
: This share is not participating in replication.split_pending
: This share is performing a replication split.
The enumerated values for this property may expand in the future.
Possible values: [
active
,degraded
,failover_pending
,initializing
,none
,split_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current replication status (if any).
The resource group for this file share
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the file share rounded up to the next gigabyte.
The maximum size for a share may increase in the future.
Possible values: 10 ≤ value ≤ 32000
Example:
200
Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The zone this file share will reside in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The key used to encrypt this file share.
This property will be present if
encryption
isuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The latest job associated with this file share.
This property will be absent if no jobs have been created for this file share.
The status of the file share job:
cancelled
: This job has been cancelled.failed
: This job has failed.queued
: This job is queued.running
: This job is running.succeeded
: This job completed successfully.
The enumerated values for this property may expand in the future.
Possible values: [
cancelled
,failed
,queued
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the file share job status (if any).
The type of the file share job:
replication_failover
: This is a share replication failover job.replication_init
: This is a share replication is initialization job.replication_split
: This is a share replication split job.
The enumerated values for this property may expand in the future.
Possible values: [
replication_failover
,replication_init
,replication_split
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
latest_job
Information about the latest synchronization for this file share.
This property will be present when the
replication_role
isreplica
and at least one replication sync has been completed.The replica file share for this source file share.
This property will be present when the
replication_role
issource
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
replica_share
The cron specification for the file share replication schedule.
This property will be present when the
replication_role
isreplica
.Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
0 */5 * * *
The source file share for this replica file share.
This property will be present when the
replication_role
isreplica
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_share
Status Code
The file share was created successfully.
An invalid file share prototype object was provided.
The share prototype object specified one or more of:
- share mount targets in the same VPC
- an encryption key that cannot be used in its current state
- a virtual network interface with
allow_ip_spoofing
set totrue
- a virtual network interface with
enable_infrastructure_nat
set tofalse
- a virtual network interface with
ips
other than theprimary_ip
address - a virtual network interface with a floating IP bound to it
- a virtual network interface that is the target of a flow log collector
{ "access_control_mode": "security_group", "created_at": "2021-04-24T22:58:49.000Z", "crn": "crn:[...]", "encryption": "provider_managed", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "iops": 14400, "lifecycle_state": "pending", "mount_targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "name": "my-share-mount-target", "resource_type": "share_mount_target", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc" } } ], "name": "my-share", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops", "name": "tier-3iops", "resource_type": "share_profile" }, "replication_role": "none", "replication_status": "none", "replication_status_reasons": [], "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "share", "size": 4800, "user_tags": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a file share
This request deletes a share. This operation cannot be reversed. A share cannot be deleted if it:
- has share mount targets
- has a
lifecycle_state
ofupdating
- has a replication operation in progress
If the request is accepted, the share lifecycle_state
will be set to deleting
.
Once deletion processing completes, it will no longer be retrievable.
DELETE /shares/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/shares/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteShareOptions := &vpcv1.DeleteShareOptions{ ID: &shareId, IfMatch: &shareETag, } share, response, err := vpcService.DeleteShare(deleteShareOptions)
DeleteShareOptions deleteShareOptions = new DeleteShareOptions.Builder() .id(shareId) .ifMatch(shareETag) .build(); Response<Share> response = vpcService.deleteShare(deleteShareOptions).execute(); Share share = response.getResult();
const params = { id: shareId, ifMatch: shareETag, }; const response = await vpcService.deleteShare(params);
response = vpc_service.delete_share( id=shareId, if_match=shareETag )
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the file share is created
The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The type of encryption used for this file share
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The maximum input/output operations per second (IOPS) for the file share. In addition, each client accessing the share will be restricted to 48,000 IOPS.
The maximum IOPS for a share may increase in the future.
Possible values: 100 ≤ value ≤ 96000
Example:
100
The lifecycle state of the file share
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The mount targets for the file share
Possible values: number of items ≥ 0
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The profile for this file share
The URL for this share profile.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
The resource type
Possible values: [
share_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The replication role of the file share:
none
: This share is not participating in replication.replica
: This share is a replication target.source
: This share is a replication source.
The enumerated values for this property may expand in the future.
Possible values: [
none
,replica
,source
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The replication status of the file share:
active
: This share is actively participating in replication, and the replica's data is up-to-date with the replication schedule.degraded
: This is share is participating in replication, but the replica's data has fallen behind the replication schedule.failover_pending
: This share is performing a replication failover.initializing
: This share is initializing replication.none
: This share is not participating in replication.split_pending
: This share is performing a replication split.
The enumerated values for this property may expand in the future.
Possible values: [
active
,degraded
,failover_pending
,initializing
,none
,split_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current replication status (if any).
The resource group for this file share
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the file share rounded up to the next gigabyte.
The maximum size for a share may increase in the future.
Possible values: 10 ≤ value ≤ 32000
Example:
200
Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The zone this file share will reside in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The key used to encrypt this file share.
This property will be present if
encryption
isuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The latest job associated with this file share.
This property will be absent if no jobs have been created for this file share.
The status of the file share job:
cancelled
: This job has been cancelled.failed
: This job has failed.queued
: This job is queued.running
: This job is running.succeeded
: This job completed successfully.
The enumerated values for this property may expand in the future.
Possible values: [
cancelled
,failed
,queued
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the file share job status (if any).
The type of the file share job:
replication_failover
: This is a share replication failover job.replication_init
: This is a share replication is initialization job.replication_split
: This is a share replication split job.
The enumerated values for this property may expand in the future.
Possible values: [
replication_failover
,replication_init
,replication_split
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
latest_job
Information about the latest synchronization for this file share.
This property will be present when the
replication_role
isreplica
and at least one replication sync has been completed.The replica file share for this source file share.
This property will be present when the
replication_role
issource
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
replica_share
The cron specification for the file share replication schedule.
This property will be present when the
replication_role
isreplica
.Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
0 */5 * * *
The source file share for this replica file share.
This property will be present when the
replication_role
isreplica
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_share
Status Code
The file share deletion request was accepted.
A file share with the specified identifier could not be found.
The file share cannot be deleted in its current state.
The provided
If-Match
value does not match the current ETag value of the share
{ "access_control_mode": "security_group", "created_at": "2021-04-24T22:58:49.000Z", "crn": "crn:[...]", "encryption": "provider_managed", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "iops": 14400, "lifecycle_state": "deleting", "mount_targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "name": "my-share-mount-target", "resource_type": "share_mount_target", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc" } } ], "name": "my-share", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops", "name": "tier-3iops", "resource_type": "share_profile" }, "replication_role": "none", "replication_status": "none", "replication_status_reasons": [], "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "share", "size": 4800, "user_tags": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Retrieve a file share
This request retrieves a single file share specified by the identifier in the URL.
GET /shares/{id}
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/shares/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getShareOptions := &vpcv1.GetShareOptions{ ID: &shareId, } share, response, err := vpcService.GetShare(getShareOptions)
GetShareOptions getShareOptions = new GetShareOptions.Builder() .id(shareId) .build(); Response<Share> response = vpcService.getShare(getShareOptions).execute(); Share share = response.getResult();
const params = { id: data.shareId, }; const response = await vpcService.getShare(params);
response = vpc_service.get_share( id=shareId, ) share = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the file share is created
The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The type of encryption used for this file share
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The maximum input/output operations per second (IOPS) for the file share. In addition, each client accessing the share will be restricted to 48,000 IOPS.
The maximum IOPS for a share may increase in the future.
Possible values: 100 ≤ value ≤ 96000
Example:
100
The lifecycle state of the file share
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The mount targets for the file share
Possible values: number of items ≥ 0
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The profile for this file share
The URL for this share profile.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
The resource type
Possible values: [
share_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The replication role of the file share:
none
: This share is not participating in replication.replica
: This share is a replication target.source
: This share is a replication source.
The enumerated values for this property may expand in the future.
Possible values: [
none
,replica
,source
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The replication status of the file share:
active
: This share is actively participating in replication, and the replica's data is up-to-date with the replication schedule.degraded
: This is share is participating in replication, but the replica's data has fallen behind the replication schedule.failover_pending
: This share is performing a replication failover.initializing
: This share is initializing replication.none
: This share is not participating in replication.split_pending
: This share is performing a replication split.
The enumerated values for this property may expand in the future.
Possible values: [
active
,degraded
,failover_pending
,initializing
,none
,split_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current replication status (if any).
The resource group for this file share
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the file share rounded up to the next gigabyte.
The maximum size for a share may increase in the future.
Possible values: 10 ≤ value ≤ 32000
Example:
200
Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The zone this file share will reside in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The key used to encrypt this file share.
This property will be present if
encryption
isuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The latest job associated with this file share.
This property will be absent if no jobs have been created for this file share.
The status of the file share job:
cancelled
: This job has been cancelled.failed
: This job has failed.queued
: This job is queued.running
: This job is running.succeeded
: This job completed successfully.
The enumerated values for this property may expand in the future.
Possible values: [
cancelled
,failed
,queued
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the file share job status (if any).
The type of the file share job:
replication_failover
: This is a share replication failover job.replication_init
: This is a share replication is initialization job.replication_split
: This is a share replication split job.
The enumerated values for this property may expand in the future.
Possible values: [
replication_failover
,replication_init
,replication_split
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
latest_job
Information about the latest synchronization for this file share.
This property will be present when the
replication_role
isreplica
and at least one replication sync has been completed.The replica file share for this source file share.
This property will be present when the
replication_role
issource
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
replica_share
The cron specification for the file share replication schedule.
This property will be present when the
replication_role
isreplica
.Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
0 */5 * * *
The source file share for this replica file share.
This property will be present when the
replication_role
isreplica
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_share
Status Code
The file share was retrieved successfully
A file share with the specified identifier could not be found.
{ "access_control_mode": "security_group", "created_at": "2021-04-24T22:58:49.000Z", "crn": "crn:[...]", "encryption": "provider_managed", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "iops": 14400, "lifecycle_state": "stable", "mount_targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "name": "my-share-mount-target", "resource_type": "share_mount_target", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc" } } ], "name": "my-share", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops", "name": "tier-3iops", "resource_type": "share_profile" }, "replication_role": "none", "replication_status": "none", "replication_status_reasons": [], "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "share", "size": 4800, "user_tags": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a file share
This request updates a share with the information in a provided share patch. The share patch object is structured in the same way as a retrieved share and contains only the information to be updated.
PATCH /shares/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The file share patch
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
For this property to be changed, the share must have no mount targets and
replication_role
must benone
.Allowable values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The maximum input/output operations per second (IOPS) for the file share. The value must be in the range supported by the share's size.
For this property to be changed, the share
lifecycle_state
must bestable
,replication_role
must not bereplica
, the share must be in thecustom
ordefined_performance
profile family.Possible values: 100 ≤ value ≤ 96000
Example:
100
The name for this share. The name must not be used by another share in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The profile to use for this file share.
The requested profile must be in the same
family
, with the following exceptions:- If the current profile family is
tiered
, the requested profile family may becustom
ordefined_performance
. - If the current profile family is
custom
, the requested profile family may betiered
ordefined_performance
. Additionally, if requested profile family istiered
, theniops
will be reset to a value based on the specified profile and current share size, and will become immutable. - If the current profile family is
defined_performance
, the requested profile family may betiered
orcustom
. Additionally, if requested profile family istiered
, theniops
will be reset to a value based on the specified profile and current share size, and will become immutable.
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
profile
- If the current profile family is
The cron specification for the file share replication schedule.
Replication of a share can be scheduled to occur at most once per hour.
For this property to be changed, the share
replication_role
must bereplica
.Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
0 */5 * * *
The size of the file share rounded up to the next gigabyte. The value must not be less than the share's current size, and must not exceed the maximum supported by the share's profile and IOPS.
For this property to be changed, the share
lifecycle_state
must bestable
andreplication_role
must not bereplica
.Possible values: 10 ≤ value ≤ 32000
Example:
200
Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
curl -X PATCH "$vpc_api_endpoint/v1/shares/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-share-updated" }'
sharePatchModel := &vpcv1.SharePatch{ Name: &[]string{"my-share-updated"}[0], } sharePatchModelAsPatch, asPatchErr := sharePatchModel.AsPatch() updateShareOptions := &vpcv1.UpdateShareOptions{ ID: &shareId, IfMatch: &shareETag, SharePatch: sharePatchModelAsPatch, } share, response, err := vpcService.UpdateShare(updateShareOptions)
SharePatch sharePatchModel = new SharePatch.Builder() .name("my-share-updated") .addUserTags("my-share-tag-updated") .size(300) .iops(300) .build(); Map<String, Object> sharePatchModelAsPatch = sharePatchModel.asPatch(); UpdateShareOptions updateShareOptions = new UpdateShareOptions.Builder() .id(shareId) .sharePatch(sharePatchModelAsPatch) .ifMatch(shareETag) .build(); Response<Share> response = vpcService.updateShare(updateShareOptions).execute(); Share share = response.getResult();
const params = { id: shareId, ifMatch: shareETag, accessControlMode: 'security_group', iops: 200, name: 'my-share', size: 300, userTags: ['my-share-tag-updated'], }; const response = await vpcService.updateShare(params);
share_patch_model = { 'name': 'my-share-updated' } response = vpc_service.update_share( id=shareId, share_patch=share_patch_model, if_match=shareETag ) share = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the file share is created
The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The type of encryption used for this file share
Possible values: [
provider_managed
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
provider_managed
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The maximum input/output operations per second (IOPS) for the file share. In addition, each client accessing the share will be restricted to 48,000 IOPS.
The maximum IOPS for a share may increase in the future.
Possible values: 100 ≤ value ≤ 96000
Example:
100
The lifecycle state of the file share
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The mount targets for the file share
Possible values: number of items ≥ 0
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The profile for this file share
The URL for this share profile.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops
The globally unique name for this share profile.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
tier-3iops
The resource type
Possible values: [
share_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
profile
The replication role of the file share:
none
: This share is not participating in replication.replica
: This share is a replication target.source
: This share is a replication source.
The enumerated values for this property may expand in the future.
Possible values: [
none
,replica
,source
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The replication status of the file share:
active
: This share is actively participating in replication, and the replica's data is up-to-date with the replication schedule.degraded
: This is share is participating in replication, but the replica's data has fallen behind the replication schedule.failover_pending
: This share is performing a replication failover.initializing
: This share is initializing replication.none
: This share is not participating in replication.split_pending
: This share is performing a replication split.
The enumerated values for this property may expand in the future.
Possible values: [
active
,degraded
,failover_pending
,initializing
,none
,split_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current replication status (if any).
The resource group for this file share
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The size of the file share rounded up to the next gigabyte.
The maximum size for a share may increase in the future.
Possible values: 10 ≤ value ≤ 32000
Example:
200
Tags for this resource.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
The zone this file share will reside in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The key used to encrypt this file share.
This property will be present if
encryption
isuser_managed
.The CRN of the Key Protect Root Key or Hyper Protect Crypto Services Root Key for this resource.
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:kms:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:e4a29d1a-2ef0-42a6-8fd2-350deb1c647e:key:5437653b-c4b1-447f-9646-b2a2a4cd6179
encryption_key
The latest job associated with this file share.
This property will be absent if no jobs have been created for this file share.
The status of the file share job:
cancelled
: This job has been cancelled.failed
: This job has failed.queued
: This job is queued.running
: This job is running.succeeded
: This job completed successfully.
The enumerated values for this property may expand in the future.
Possible values: [
cancelled
,failed
,queued
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the file share job status (if any).
The type of the file share job:
replication_failover
: This is a share replication failover job.replication_init
: This is a share replication is initialization job.replication_split
: This is a share replication split job.
The enumerated values for this property may expand in the future.
Possible values: [
replication_failover
,replication_init
,replication_split
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
latest_job
Information about the latest synchronization for this file share.
This property will be present when the
replication_role
isreplica
and at least one replication sync has been completed.The replica file share for this source file share.
This property will be present when the
replication_role
issource
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
replica_share
The cron specification for the file share replication schedule.
This property will be present when the
replication_role
isreplica
.Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
0 */5 * * *
The source file share for this replica file share.
This property will be present when the
replication_role
isreplica
.The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
source_share
Status Code
The file share was updated successfully.
An invalid file share patch was provided.
A file share with the specified identifier could not be found.
The file share cannot update the specified properties in its current state.
The provided
If-Match
value does not match the current ETag value of the share
{ "access_control_mode": "security_group", "created_at": "2021-04-24T22:58:49.000Z", "crn": "crn:[...]", "encryption": "provider_managed", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "iops": 14400, "lifecycle_state": "stable", "mount_targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "name": "my-share-mount-target", "resource_type": "share_mount_target", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc" } } ], "name": "my-share-updated", "profile": { "href": "https://us-south.iaas.cloud.ibm.com/v1/share/profiles/tier-3iops", "name": "tier-3iops", "resource_type": "share_profile" }, "replication_role": "none", "replication_status": "none", "replication_status_reasons": [], "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "share", "size": 4800, "user_tags": [], "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Failover to replica file share
This request triggers a failover to the replica file share specified by the identifier in
the URL. The failover cannot be started if a source share or the replica share
has a lifecycle_state
of updating
, or has a replication operation in progress.
If fallback_policy
is specified as split
, and the request is accepted but the failover
operation cannot be performed, a split will be triggered.
POST /shares/{share_id}/failover
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Options to control the failover operation
The action to take if the failover request is accepted but cannot be performed or times out:
fail
: Fail the operation, resulting in the replication relationship being unchanged.split
: Split the replica from its source, resulting in two individual read-write file shares. Because the final sync was not completed, the replica may be out-of-date. This occurs in disaster recovery scenarios where the source is known to be unreachable.
Allowable values: [
fail
,split
]Default:
split
Example:
fail
The failover timeout in seconds.
If the timeout is reached, the
fallback_policy
will be triggered.Possible values: 300 ≤ value ≤ 3600
Default:
3600
Example:
600
curl -X POST "$vpc_api_endpoint/v1/shares/$share_id/failover?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
failoverShareOptions := &vpcv1.FailoverShareOptions{ ShareID: &shareId, } response, err := vpcService.FailoverShare(failoverShareOptions)
FailoverShareOptions failoverShareOptions = new FailoverShareOptions.Builder() .shareId(shareId) .build(); Response<Void> response = vpcService.failoverShare(failoverShareOptions).execute();
const params = { shareId: shareId, }; await vpcService.failoverShare(params);
response = vpc_service.failover_share( share_id=shareId, )
List all mount targets for a file share
This request retrieves all share mount targets for a file share. A share mount target is a network endpoint at which a file share may be mounted. The file share can be mounted by clients in the same VPC and zone after creating share mount targets.
The share mount targets will be sorted by their created_at
property values, with newest
targets first.
GET /shares/{share_id}/mount_targets
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
name
property matching the exact specified name.A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/shares/$share_id/mount_targets?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listShareMountTargetsOptions := &vpcv1.ListShareMountTargetsOptions{ ShareID: &shareId, } shareMountTargetCollection, response, err := vpcService.ListShareMountTargets(listShareMountTargetsOptions)
ListShareMountTargetsOptions listShareMountTargetsOptions = new ListShareMountTargetsOptions.Builder() .shareId(shareId) .build(); Response<ShareMountTargetCollection> response = vpcService.listShareMountTargets(listShareMountTargetsOptions).execute(); ShareMountTargetCollection shareMountTargetCollection = response.getResult();
const params = { shareId: shareId, }; const response = await vpcService.listShareMountTargets(params);
response = vpc_service.list_share_mount_targets( share_id=shareId, ) share_mount_target_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of share mount targets
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The share mount targets were retrieved successfully.
A file share with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets?limit=50" }, "limit": 50, "mount_targets": [ { "access_control_mode": "security_group", "created_at": "2021-04-29T01:59:46.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "lifecycle_state": "stable", "mount_path": "fsf-dal1099a-fz.adn.networklayer.com:/nxg_s_voll_mz0716_a4cc07a3_4425_4adf_aed6_0d7e142bee0c", "name": "my-share-mount-target", "primary_ip": { "address": "10.10.12.64", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "id": "0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "share_mount_target", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "transit_encryption": "none", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc", "transit_encryption": "none" } } ], "total_count": 1 }
Create a mount target for a file share
This request creates a new share mount target from a share mount target prototype object.
The prototype object is structured in the same way as a retrieved share mount target, and contains the information necessary to provision the new file share mount target.
POST /shares/{share_id}/mount_targets
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.share.share.update
is.share.mount-target.create
is.share.mount-target.attach
is.vpc.vpc.attach
Generated for the VPC when
access_control_mode
isvpc
.is.virtual-network-interface.virtual-network-interface.create
Generated when a new virtual network interface is created.
is.virtual-network-interface.virtual-network-interface.attach
Generated when a virtual network interface is attached to a share mount target. Also generated for each reserved IP being attached to a new virtual network interface.
is.subnet.reserved-ip.create
Generated for each reserved IP created.
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to a new virtual network interface.
is.subnet.subnet.update
Generated for each reserved IP created.
is.security-group.security-group.attach
Generated for each security group being attached to a new virtual network interface.
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The share mount target prototype object
The name for this share mount target. The name must not be used by another mount target for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The transit encryption mode to use for this share mount target:
none
: Not encrypted in transit.user_managed
: Encrypted in transit using an instance identity certificate. Theaccess_control_mode
for the share must besecurity_group
.
Allowable values: [
none
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
none
Example:
none
The virtual network interface for this share mount target. The virtual network interface must:
- be in the same
zone
as the share - have
allow_ip_spoofing
set tofalse
- have
enable_infrastructure_nat
set totrue
- not be in the same VPC as an existing mount target for this share
- not have
ips
other than theprimary_ip
address
If an existing virtual network interface is specified, it must not have a floating IP bound to it, and it must not be the target of a flow log collector.
Required if the share's
access_control_mode
issecurity_group
.One of
- be in the same
curl -X POST "$vpc_api_endpoint/v1/shares/$share_id/mount_targets?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-share-mount-target", "vpc": { "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084" } }'
virtualNetworkInterfacePrimaryIPPrototype := &vpcv1.VirtualNetworkInterfacePrimaryIPPrototype{ Address: &[]string{"10.0.1.3"}[0], Name: &[]string{"my-reserved-ip"}[0], } securityGroupIdentityModel := &vpcv1.SecurityGroupIdentityByID{ ID: &securityGroupId, } subnetIdentityModel := &vpcv1.SubnetIdentityByID{ ID: &subnetId, } shareMountTargetVirtualNetworkInterfacePrototype := &vpcv1.ShareMountTargetVirtualNetworkInterfacePrototype{ Name: &[]string{"my-virtual-network-interface"}[0], PrimaryIP: virtualNetworkInterfacePrimaryIPPrototype, SecurityGroups: []vpcv1.SecurityGroupIdentityIntf{securityGroupIdentityModel}, Subnet: subnetIdentityModel, } shareMountTargetPrototypeModel := &vpcv1.ShareMountTargetPrototypeShareMountTargetByAccessControlModeSecurityGroup{ Name: &[]string{"my-share-mount-target"}[0], TransitEncryption: &[]string{"user_managed"}[0], VirtualNetworkInterface: shareMountTargetVirtualNetworkInterfacePrototype, } createShareMountTargetOptions := &vpcv1.CreateShareMountTargetOptions{ ShareID: &shareId, ShareMountTargetPrototype: shareMountTargetPrototypeModel, } shareMountTarget, response, err := vpcService.CreateShareMountTarget(createShareMountTargetOptions)
VirtualNetworkInterfacePrimaryIPPrototypeReservedIPPrototypeVirtualNetworkInterfacePrimaryIPContext virtualNetworkInterfacePrimaryIpPrototypeModel = new VirtualNetworkInterfacePrimaryIPPrototypeReservedIPPrototypeVirtualNetworkInterfacePrimaryIPContext.Builder() .address("10.0.1.3") .name("my-reserved-ip") .build(); SecurityGroupIdentityById securityGroupIdentityModel = new SecurityGroupIdentityById.Builder() .id(securityGroupId) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); ShareMountTargetVirtualNetworkInterfacePrototypeVirtualNetworkInterfacePrototypeShareMountTargetContext shareMountTargetVirtualNetworkInterfacePrototypeModel = new ShareMountTargetVirtualNetworkInterfacePrototypeVirtualNetworkInterfacePrototypeShareMountTargetContext.Builder() .name("my-virtual-network-interface") .primaryIp(virtualNetworkInterfacePrimaryIpPrototypeModel) .securityGroups(java.util.Arrays.asList(securityGroupIdentityModel)) .subnet(subnetIdentityModel) .build(); ShareMountTargetPrototypeShareMountTargetByAccessControlModeSecurityGroup shareMountTargetPrototypeModel = new ShareMountTargetPrototypeShareMountTargetByAccessControlModeSecurityGroup.Builder() .name("my-share-mount-target") .transitEncryption("user_managed") .virtualNetworkInterface(shareMountTargetVirtualNetworkInterfacePrototypeModel) .build(); CreateShareMountTargetOptions createShareMountTargetOptions = new CreateShareMountTargetOptions.Builder() .shareId(shareId) .shareMountTargetPrototype(shareMountTargetPrototypeModel) .build(); Response<ShareMountTarget> response = vpcService.createShareMountTarget(createShareMountTargetOptions).execute(); ShareMountTarget shareMountTargetResult = response.getResult();
const virtualNetworkInterfacePrimaryIpPrototypeModel = { address: '10.0.1.3', name: 'my-reserved-ip', }; const securityGroupIdentityModel = { id: securityGroupId, }; const subnetIdentityModel = { id: subnetId, }; const shareMountTargetVirtualNetworkInterfacePrototypeModel = { name: 'my-virtual-network-interface', primary_ip: virtualNetworkInterfacePrimaryIpPrototypeModel, security_groups: [securityGroupIdentityModel], subnet: subnetIdentityModel, }; const shareMountTargetPrototypeModel = { name: 'my-share-mount-target', transit_encryption: 'user_managed', virtual_network_interface: shareMountTargetVirtualNetworkInterfacePrototypeModel, }; const params = { shareId: shareId, shareMountTargetPrototype: shareMountTargetPrototypeModel, }; const response = await vpcService.createShareMountTarget(params);
virtual_network_interface_primary_ip_reserved_ip_prototype_model = { 'address': '10.240.0.15', 'name': 'my-reserved-ip', } security_group_identity_model = { 'id': security_group_id, } subnet_identity_model = { 'id': subnetId, } virtual_network_interface_prototype_share_mount_target_context_model = { 'name': 'my-virtual-network-interface', 'primary_ip': virtual_network_interface_primary_ip_reserved_ip_prototype_model, 'security_groups': [security_group_identity_model], 'subnet': subnet_identity_model, } share_mount_target_prototype_model = { 'name': 'my-share-mount-target', 'transit_encryption': 'user_managed', 'virtual_network_interface': virtual_network_interface_prototype_share_mount_target_context_model } response = vpc_service.create_share_mount_target( share_id=shareId, share_mount_target_prototype=share_mount_target_prototype_model, ) share_mount_target = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the share mount target was created
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The lifecycle state of the mount target
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transit encryption mode for this share mount target:
none
: Not encrypted in transituser_managed
: Encrypted in transit using an instance identity certificate
The enumerated values for this property may expand in the future.
Possible values: [
none
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
none
If
access_control_mode
is:security_group
: The VPC for the virtual network interface for this share mount targetvpc
: The VPC in which clients can mount the file share using this share mount target
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The mount path for the share. The server component of the mount path may be either an IP address or a fully qualified domain name.
This property will be absent if the
lifecycle_state
of the mount target is 'pending',failed
, ordeleting
.If the share's
access_control_mode
is:security_group
: The IP address used in the mount path is theprimary_ip
address of the virtual network interface for this share mount target.vpc
: The fully-qualified domain name used in the mount path is an address that resolves to the share mount target.
Possible values: 1 ≤ length ≤ 4351, Value must match regular expression
^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))|([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*):(\/|((\/([^\/\0]+(\/)?))+))$
Example:
10.240.1.23:/nxg_s_voll_mz7121_58e7e963_8f4b_4a0c_b71a_8ba8d9cd1e2e
The primary IP address of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The subnet of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The virtual network interface for this file share mount target.
This property will be present when the
access_control_mode
issecurity_group
.The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The share mount target was created successfully.
An invalid share mount target prototype object was provided.
A file share with the specified identifier could not be found.
The provided share mount target prototype specified one or more of:
- properties that conflict with the
access_control_mode
of the share - the same VPC as an existing mount target for the share
- a virtual network interface with
allow_ip_spoofing
set totrue
- a virtual network interface with
enable_infrastructure_nat
set tofalse
- a virtual network interface with
ips
other than theprimary_ip
address - a virtual network interface with a floating IP bound to it
- a virtual network interface that is the target of a flow log collector
- properties that conflict with the
{ "access_control_mode": "security_group", "created_at": "2021-04-29T01:59:46.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "lifecycle_state": "pending", "mount_path": "fsf-dal1099a-fz.adn.networklayer.com:/nxg_s_voll_mz0716_a4cc07a3_4425_4adf_aed6_0d7e142bee0c", "name": "my-share-mount-target", "primary_ip": { "address": "10.10.12.64", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "id": "0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "share_mount_target", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "transit_encryption": "none", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc", "transit_encryption": "none" } }
Delete a share mount target
This request deletes a share mount target. This operation cannot be reversed.
If the request is accepted, the share mount target lifecycle_state
will be set to
deleting
. Once deletion processing completes, it will no longer be retrievable.
DELETE /shares/{share_id}/mount_targets/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.share.share.update
is.share.mount-target.delete
is.share.mount-target.detach
is.vpc.vpc.detach
Generated for the VPC when
access_control_mode
isvpc
is.virtual-network-interface.virtual-network-interface.delete
Generated when the virtual network interface had
auto_delete
set totrue
is.virtual-network-interface.virtual-network-interface.detach
Generated for the virtual network interface that was attached to the share mount target. Also generated for each reserved IP that was attached to a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.detach
Generated for each reserved IP that was attached to a virtual network interface that had
auto_delete
set totrue
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
that was attached to a virtual network interface that hadauto_delete
set totrue
is.security-group.security-group.detach
Generated for each security group that was attached to a virtual network interface that had
auto_delete
set totrue
Request
Path Parameters
The file share identifier
The share mount target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/shares/$share_id/mount_targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteShareMountTargetOptions := &vpcv1.DeleteShareMountTargetOptions{ ShareID: &shareId, ID: &shareMountTargetId, } shareMountTarget, response, err := vpcService.DeleteShareMountTarget(deleteShareMountTargetOptions)
DeleteShareMountTargetOptions deleteShareMountTargetOptions = new DeleteShareMountTargetOptions.Builder() .shareId(shareId) .id(shareMountTargetId) .build(); Response<ShareMountTarget> response = vpcService.deleteShareMountTarget(deleteShareMountTargetOptions).execute(); ShareMountTarget shareMountTarget = response.getResult();
const params = { shareId: shareId, id: shareMountTargetId, }; const response = await vpcService.deleteShareMountTarget(params);
response = vpc_service.delete_share_mount_target( share_id=shareId, id=shareMountTargetId, ) share_mount_target = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the share mount target was created
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The lifecycle state of the mount target
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transit encryption mode for this share mount target:
none
: Not encrypted in transituser_managed
: Encrypted in transit using an instance identity certificate
The enumerated values for this property may expand in the future.
Possible values: [
none
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
none
If
access_control_mode
is:security_group
: The VPC for the virtual network interface for this share mount targetvpc
: The VPC in which clients can mount the file share using this share mount target
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The mount path for the share. The server component of the mount path may be either an IP address or a fully qualified domain name.
This property will be absent if the
lifecycle_state
of the mount target is 'pending',failed
, ordeleting
.If the share's
access_control_mode
is:security_group
: The IP address used in the mount path is theprimary_ip
address of the virtual network interface for this share mount target.vpc
: The fully-qualified domain name used in the mount path is an address that resolves to the share mount target.
Possible values: 1 ≤ length ≤ 4351, Value must match regular expression
^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))|([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*):(\/|((\/([^\/\0]+(\/)?))+))$
Example:
10.240.1.23:/nxg_s_voll_mz7121_58e7e963_8f4b_4a0c_b71a_8ba8d9cd1e2e
The primary IP address of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The subnet of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The virtual network interface for this file share mount target.
This property will be present when the
access_control_mode
issecurity_group
.The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The share mount target deletion request was accepted.
A share mount target with the specified identifier could not be found for the file share with the specified identifier.
{ "access_control_mode": "security_group", "created_at": "2021-04-29T01:59:46.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "lifecycle_state": "deleting", "mount_path": "fsf-dal1099a-fz.adn.networklayer.com:/nxg_s_voll_mz0716_a4cc07a3_4425_4adf_aed6_0d7e142bee0c", "name": "my-share-mount-target", "primary_ip": { "address": "10.10.12.64", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "id": "0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "share_mount_target", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "transit_encryption": "none", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc", "transit_encryption": "none" } }
Retrieve a share mount target
This request retrieves a single share mount target specified by the identifier in the URL.
GET /shares/{share_id}/mount_targets/{id}
Request
Path Parameters
The file share identifier
The share mount target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/shares/$share_id/mount_targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getShareMountTargetOptions := &vpcv1.GetShareMountTargetOptions{ ShareID: &shareId, ID: &shareMountTargetId, } shareMountTarget, response, err := vpcService.GetShareMountTarget(getShareMountTargetOptions)
GetShareMountTargetOptions getShareMountTargetOptions = new GetShareMountTargetOptions.Builder() .shareId(shareId) .id(shareMountTargetId) .build(); Response<ShareMountTarget> response = vpcService.getShareMountTarget(getShareMountTargetOptions).execute(); ShareMountTarget shareMountTarget = response.getResult();
const params = { shareId: shareId, id: shareMountTargetId, }; const response = await vpcService.getShareMountTarget(params);
response = vpc_service.get_share_mount_target( share_id=shareId, id=shareMountTargetId, ) share_mount_target = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the share mount target was created
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The lifecycle state of the mount target
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transit encryption mode for this share mount target:
none
: Not encrypted in transituser_managed
: Encrypted in transit using an instance identity certificate
The enumerated values for this property may expand in the future.
Possible values: [
none
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
none
If
access_control_mode
is:security_group
: The VPC for the virtual network interface for this share mount targetvpc
: The VPC in which clients can mount the file share using this share mount target
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The mount path for the share. The server component of the mount path may be either an IP address or a fully qualified domain name.
This property will be absent if the
lifecycle_state
of the mount target is 'pending',failed
, ordeleting
.If the share's
access_control_mode
is:security_group
: The IP address used in the mount path is theprimary_ip
address of the virtual network interface for this share mount target.vpc
: The fully-qualified domain name used in the mount path is an address that resolves to the share mount target.
Possible values: 1 ≤ length ≤ 4351, Value must match regular expression
^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))|([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*):(\/|((\/([^\/\0]+(\/)?))+))$
Example:
10.240.1.23:/nxg_s_voll_mz7121_58e7e963_8f4b_4a0c_b71a_8ba8d9cd1e2e
The primary IP address of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The subnet of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The virtual network interface for this file share mount target.
This property will be present when the
access_control_mode
issecurity_group
.The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The share mount target was retrieved successfully.
A share mount target with the specified identifier could not be found for the file share with the specified identifier.
{ "access_control_mode": "security_group", "created_at": "2021-04-29T01:59:46.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "lifecycle_state": "stable", "mount_path": "fsf-dal1099a-fz.adn.networklayer.com:/nxg_s_voll_mz0716_a4cc07a3_4425_4adf_aed6_0d7e142bee0c", "name": "my-share-mount-target", "primary_ip": { "address": "10.10.12.64", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "id": "0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "share_mount_target", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "transit_encryption": "none", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc", "transit_encryption": "none" } }
Update a share mount target
This request updates a share mount target with the information provided in a share mount target patch object. The share mount target patch object is structured in the same way as a retrieved share mount target and needs to contain only the information to be updated.
PATCH /shares/{share_id}/mount_targets/{id}
Request
Path Parameters
The file share identifier
The share mount target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The share mount target patch
The name for this share mount target. The name must not be used by another mount target for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
curl -X PATCH "$vpc_api_endpoint/v1/shares/$share_id/mount_targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-share-mount-target-updated" }'
shareMountTargetPatchModel := &vpcv1.ShareMountTargetPatch{ Name: &[]string{"my-share-mount-target-updated"}[0], } shareMountTargetPatchModelAsPatch, asPatchErr := shareMountTargetPatchModel.AsPatch() updateShareMountTargetOptions := &vpcv1.UpdateShareMountTargetOptions{ ShareID: &shareId, ID: &shareMountTargetId, ShareMountTargetPatch: shareMountTargetPatchModelAsPatch, } shareMountTarget, response, err := vpcService.UpdateShareMountTarget(updateShareMountTargetOptions)
ShareMountTargetPatch shareMountTargetPatchModel = new ShareMountTargetPatch.Builder() .name("my-share-mount-target-updated") .build(); Map<String, Object> shareMountTargetPatchModelAsPatch = shareMountTargetPatchModel.asPatch(); UpdateShareMountTargetOptions updateShareMountTargetOptions = new UpdateShareMountTargetOptions.Builder() .shareId(shareId) .id(shareMountTargetId) .shareMountTargetPatch(shareMountTargetPatchModelAsPatch) .build(); Response<ShareMountTarget> response = vpcService.updateShareMountTarget(updateShareMountTargetOptions).execute(); ShareMountTarget shareMountTarget = response.getResult();
const params = { shareId: shareId, id: shareMountTargetId, name: 'my-share-mount-target-updated', }; const response = await vpcService.updateShareMountTarget(params);
share_mount_target_patch_model = { 'name': 'my-share-mount-target-updated' } response = vpc_service.update_share_mount_target( share_id=shareId, id=shareMountTargetId, share_mount_target_patch=share_mount_target_patch_model, ) share_mount_target = response.get_result()
Response
The access control mode for the share:
security_group
: The security groups on the virtual network interface for a mount target control access to the mount target.vpc
: All clients in the VPC for a mount target have access to the mount target.
The enumerated values for this property may expand in the future.
Possible values: [
security_group
,vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the share mount target was created
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The lifecycle state of the mount target
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transit encryption mode for this share mount target:
none
: Not encrypted in transituser_managed
: Encrypted in transit using an instance identity certificate
The enumerated values for this property may expand in the future.
Possible values: [
none
,user_managed
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
none
If
access_control_mode
is:security_group
: The VPC for the virtual network interface for this share mount targetvpc
: The VPC in which clients can mount the file share using this share mount target
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The mount path for the share. The server component of the mount path may be either an IP address or a fully qualified domain name.
This property will be absent if the
lifecycle_state
of the mount target is 'pending',failed
, ordeleting
.If the share's
access_control_mode
is:security_group
: The IP address used in the mount path is theprimary_ip
address of the virtual network interface for this share mount target.vpc
: The fully-qualified domain name used in the mount path is an address that resolves to the share mount target.
Possible values: 1 ≤ length ≤ 4351, Value must match regular expression
^((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))|([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])(\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]{0,61}[a-zA-Z0-9]))*):(\/|((\/([^\/\0]+(\/)?))+))$
Example:
10.240.1.23:/nxg_s_voll_mz7121_58e7e963_8f4b_4a0c_b71a_8ba8d9cd1e2e
The primary IP address of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The subnet of the virtual network interface for the share mount target.
Absent if
access_control_mode
isvpc
.Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The virtual network interface for this file share mount target.
This property will be present when the
access_control_mode
issecurity_group
.The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
virtual_network_interface
Status Code
The share mount target was updated successfully.
An invalid share mount target patch was provided.
A share mount target with the specified identifier could not be found for the file share with the specified identifier.
{ "access_control_mode": "security_group", "created_at": "2021-04-29T01:59:46.000Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86/mount_targets/r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "id": "r134-1b5571cb-536d-48d0-8452-81c05c6f7b80", "lifecycle_state": "stable", "mount_path": "fsf-dal1099a-fz.adn.networklayer.com:/nxg_s_voll_mz0716_a4cc07a3_4425_4adf_aed6_0d7e142bee0c", "name": "my-share-mount-target-updated", "primary_ip": { "address": "10.10.12.64", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "id": "0716-6fd4925d-7774-4e87-829e-7e5765d454ad", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "share_mount_target", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet", "resource_type": "subnet" }, "transit_encryption": "none", "virtual_network_interface": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-12bb28fc-856d-4902-813b-dc065d1ed084", "id": "r134-12bb28fc-856d-4902-813b-dc065d1ed084", "name": "my-vpc", "resource_type": "vpc", "transit_encryption": "none" } }
Split the source file share from a replica share
This request removes the replication relationship between a source share and
the replica share specified by the identifier in the URL.
The replication relationship cannot be removed if a source share or the replica share
has a lifecycle_state
of updating
, or has a replication operation in progress.
This operation cannot be reversed.
DELETE /shares/{share_id}/source
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/shares/$share_id/source?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteShareSourceOptions := &vpcv1.DeleteShareSourceOptions{ ShareID: &shareId, } response, err := vpcService.DeleteShareSource(deleteShareSourceOptions)
DeleteShareSourceOptions deleteShareSourceOptions = new DeleteShareSourceOptions.Builder() .shareId(shareId) .build(); Response<Void> response = vpcService.deleteShareSource(deleteShareSourceOptions).execute();
const params = { shareId: shareId, }; await vpcService.deleteShareSource(params);
response = vpc_service.delete_share_source( share_id=shareId, )
Retrieve the source file share for a replica file share
This request retrieves the source file share associated with the replica file share specified by the identifier in the URL.
GET /shares/{share_id}/source
Request
Path Parameters
The file share identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/shares/$share_id/source?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getShareSourceOptions := &vpcv1.GetShareSourceOptions{ ShareID: &shareId, } share, response, err := vpcService.GetShareSource(getShareSourceOptions)
GetShareSourceOptions getShareSourceOptions = new GetShareSourceOptions.Builder() .shareId(shareId) .build(); Response<Share> response = vpcService.getShareSource(getShareSourceOptions).execute(); Share share = response.getResult();
const params = { shareId: shareId, }; const response = await vpcService.getShareSource(params);
response = vpc_service.get_share_source( share_id=shareId, ) share = response.get_result()
Response
The CRN for this file share
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:0fe9e5d8-0a4d-4818-96ec-e99708644a58
The URL for this file share
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58
The unique identifier for this file share
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0fe9e5d8-0a4d-4818-96ec-e99708644a58
The name for this share. The name is unique across all shares in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share
The resource type
Possible values: [
share
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
Status Code
The source file share was retrieved successfully.
A replica file share with the specified identifier could not be found.
{ "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86", "id": "r134-a0c07083-f411-446c-9316-7b08d6448c86", "name": "my-source-share", "resource_type": "share" }
List all backup policies
This request lists all 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.
GET /backup_policies
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with an item in the
tags
property matching the exact specified tag.
curl -X GET "$vpc_api_endpoint/v1/backup_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listBackupPoliciesOptions := &vpcv1.ListBackupPoliciesOptions{} backupPolicyCollection, response, err := vpcService.ListBackupPolicies(listBackupPoliciesOptions)
ListBackupPoliciesOptions listBackupPoliciesOptions = new ListBackupPoliciesOptions.Builder() .build(); Response<BackupPolicyCollection> response = service.listBackupPolicies(listBackupPoliciesOptions).execute(); BackupPolicyCollection backupPolicyCollectionResult = response.getResult();
const response = await vpcService.listBackupPolicies();
backup_policy_collection = vpc_service.list_backup_policies().get_result()
Response
Collection of backup policies
backup_policies
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The backup policies were retrieved successfully
{ "backup_policies": [ { "created_at": "2022-04-21T15:06:03.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "included_content": [ "data_volume" ], "lifecycle_state": "stable", "match_resource_type": "volume", "match_user_tags": [ "my-tag-1", "my-tag-2" ], "name": "my-backup-policy", "plans": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "id": "r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" } ], "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "backup_policy", "scope": { "crn": "crn:v1:bluemix:public:enterprise::a/aa2432b1fa4d4ace891e9b80fc104e34::enterprise:ebc2b430240943458b9e91e1432cfcce", "id": "ebc2b430240943458b9e91e1432cfcce", "resource_type": "enterprise" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies?limit=50" }, "limit": 50, "total_count": 1 }
Create a backup policy
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.
POST /backup_policies
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The backup policy prototype object
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.
Allowable values: [
instance
,volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe 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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
The prototype objects for backup plans to be created for this backup policy.
Possible values: 0 ≤ number of items ≤ 4
The resource group to use. If unspecified, the account's default resource group will be used.
The scope to use for this backup policy.
If unspecified, the policy will be scoped to the account.
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.
Allowable values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
One of
curl -X POST "$vpc_api_endpoint/v1/backup_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-backup-policy", "match_user_tags": ["my-tag-1", "my-tag-2"], "match_resource_type": "volume", "plans": [{ "attach_user_tags": ["my-plan-1"], "cron_spec": "15 * * * *", "deletion_trigger": {"delete_after": 5}, "name": "my-backup-plan-1" }] }'
backupPolicyPlanDeletionTriggerPrototypeModel := &vpcv1.BackupPolicyPlanDeletionTriggerPrototype{ DeleteAfter: []int{int64(20)}[0], DeleteOverCount: []int{int64(20)}[0], } backupPolicyPlanPrototypeModel := &vpcv1.BackupPolicyPlanPrototype{ AttachUserTags: []string{"my-daily-backup-plan"}, CronSpec: []string{"*/5 1,2,3 * * *"}[0], DeletionTrigger: backupPolicyPlanDeletionTriggerPrototypeModel, Name: []string{"my-policy-plan"}[0], } createBackupPolicyOptions := &vpcv1.CreateBackupPolicyOptions{ MatchResourceType: []string{"volume"}[0], MatchUserTags: []string{"my-daily-backup-policy"}, Name: []string{"my-backup-policy"}[0], Plans: []vpcv1.BackupPolicyPlanPrototype{*backupPolicyPlanPrototypeModel}, } backupPolicy, response, err := vpcService.CreateBackupPolicy(createBackupPolicyOptions)
BackupPolicyPlanDeletionTriggerPrototype backupPolicyPlanDeletionTriggerPrototypeModel = new BackupPolicyPlanDeletionTriggerPrototype.Builder() .deleteAfter(Long.valueOf("20")) .deleteOverCount(Long.valueOf("20")) .build(); BackupPolicyPlanPrototype backupPolicyPlanPrototypeModel = new BackupPolicyPlanPrototype.Builder() .attachUserTags(new java.util.ArrayList<String>(java.util.Arrays.asList("my-daily-backup-plan"))) .cronSpec("*/5 1,2,3 * * *") .deletionTrigger(backupPolicyPlanDeletionTriggerPrototypeModel) .name("my-policy-plan") .build(); CreateBackupPolicyOptions createBackupPolicyOptions = new CreateBackupPolicyOptions.Builder() .matchResourceType("volume") .matchUserTags(new java.util.ArrayList<String>(java.util.Arrays.asList("my-daily-backup-policy"))) .name("my-backup-policy") .plans(new java.util.ArrayList<BackupPolicyPlanPrototype>(java.util.Arrays.asList(backupPolicyPlanPrototypeModel))) .build(); Response<BackupPolicy> response = service.createBackupPolicy(createBackupPolicyOptions).execute(); BackupPolicy backupPolicyResult = response.getResult();
const backupPolicyPlanDeletionTriggerPrototypeModel = { delete_after: 20, delete_over_count: 20, }; const backupPolicyPlanPrototypeModel = { attach_user_tags: ['my-daily-backup-plan'], cron_spec: '*/5 1,2,3 * * *', deletion_trigger: backupPolicyPlanDeletionTriggerPrototypeModel, name: 'my-policy-plan', }; const params = { matchUserTags: ['my-daily-backup-policy'], matchResourceType: 'volume', name: 'my-backup-policy', plans: [backupPolicyPlanPrototypeModel], }; const response = await vpcService.createBackupPolicy(params);
backup_policy_plan_deletion_trigger_prototype_model = { 'delete_after': 20, 'delete_over_count': 20 } backup_policy_plan_prototype_model = { 'attach_user_tags': ['my-daily-backup-plan'], 'cron_spec': '*/5 1,2,3 * * *', 'deletion_trigger': backup_policy_plan_deletion_trigger_prototype_model, 'name': 'my-policy-plan' } create_backup_policy_response = vpc_service.create_backup_policy( match_user_tags=['my-daily-backup-policy'], match_resource_type='volume', name='my-backup-policy', plans=[backup_policy_plan_prototype_model], ) backup_policy = create_backup_policy_response.get_result()
Response
The date and time that the backup policy was created
The CRN for this backup policy
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this backup policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The unique identifier for this backup policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The lifecycle state of the backup policy
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
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.
Possible values: [
instance
,volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe name for this backup policy. The name is unique across all backup policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
The plans for the backup policy.
The resource group for this backup policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
backup_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The scope for this backup policy.
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.
The included content for backups created using this policy:
boot_volume
: Include the instance's boot volume.data_volumes
: Include the instance's data volumes.
The enumerated values for this property may expand in the future.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
One of
Status Code
The backup policy was created successfully.
An invalid backup policy prototype object was provided.
{ "created_at": "2022-04-21T15:06:03.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "included_content": [ "data_volume" ], "lifecycle_state": "pending", "match_resource_type": "volume", "match_user_tags": [ "my-tag-1", "my-tag-2" ], "name": "my-backup-policy", "plans": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "id": "r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" } ], "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "backup_policy", "scope": { "crn": "crn:v1:bluemix:public:enterprise::a/aa2432b1fa4d4ace891e9b80fc104e34::enterprise:ebc2b430240943458b9e91e1432cfcce", "id": "ebc2b430240943458b9e91e1432cfcce", "resource_type": "enterprise" } }
List all jobs for a backup policy
This request retrieves all jobs for a backup policy. A backup job represents the execution of a backup policy plan for a resource matching the policy's criteria.
GET /backup_policies/{backup_policy_id}/jobs
Request
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to backup policy jobs with a
status
property matching the specified value.Allowable values: [
failed
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Filters the collection to backup policy jobs with a
backup_policy_plan.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to backup policy jobs with a
source.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to backup policy jobs with an item in the
target_snapshots
property with anid
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to backup policy jobs with an item in the
target_snapshots
property with acrn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-f6bfa329-0e36-433f-a3bb-0df632e79263
curl -X GET "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/jobs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listBackupPolicyJobsOptions := &vpcv1.ListBackupPolicyJobsOptions{ BackupPolicyID: &backupPolicyId, } backupPolicyJobCollection, response, err := vpcService.ListBackupPolicyJobs(listBackupPolicyJobsOptions)
ListBackupPolicyJobsOptions listBackupPolicyJobsOptions = new ListBackupPolicyJobsOptions.Builder() .backupPolicyId(backupPolicyId) .build(); Response<BackupPolicyJobCollection> response = service.listBackupPolicyJobs(listBackupPolicyJobsOptions).execute(); BackupPolicyJobCollection backupPolicyJobCollectionResult = response.getResult();
const params = { backupPolicyId } const response = await vpcService.listBackupPolicyJobs(params);
list_backup_policy_jobs_response = service.list_backup_policy_jobs( backup_policy_id=backup_policy_id, ) backup_policy_job_collection = list_backup_policy_jobs_response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/7241e2a8-601f-11ea-8503-000c29475bed/jobs?limit=20
first
Collection of backup policy jobs
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/7241e2a8-601f-11ea-8503-000c29475bed/jobss?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The backup policy jobs were retrieved successfully.
A backup policy with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-f1fedf51-f430-4ba4-bd09-29719a91350a/jobs?limit=50" }, "jobs": [ { "auto_delete": true, "auto_delete_after": 15, "backup_policy_plan": { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-f1fedf51-f430-4ba4-bd09-29719a91350a/plans/r134-9e1b0b14-21bc-4c83-9f4b-99225fd267b3", "id": "r134-9e1b0b14-21bc-4c83-9f4b-99225fd267b3", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" }, "completed_at": "2022-04-22T20:59:34Z", "created_at": "2022-04-22T20:59:11Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-f1fedf51-f430-4ba4-bd09-29719a91350a/jobs/r134-fc4b7fbc-38af-45d9-9fb6-bf0533acbf90", "id": "r134-fc4b7fbc-38af-45d9-9fb6-bf0533acbf90", "job_type": "creation", "resource_type": "backup_policy_job", "source": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "id": "r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "name": "my-volume-1", "resource_type": "volume" }, "status": "succeeded", "status_reasons": [], "target_snapshots": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-5886f8e4-5b0c-4378-9a75-82930936593e", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-5886f8e4-5b0c-4378-9a75-82930936593e", "id": "r134-5886f8e4-5b0c-4378-9a75-82930936593e", "name": "my-backup-plan-1-364d6c2da03e-447d", "resource_type": "snapshot" } ] } ], "limit": 50, "total_count": 1 }
Retrieve a backup policy job
This request retrieves a single backup policy job specified by the identifier in the URL.
GET /backup_policies/{backup_policy_id}/jobs/{id}
Request
Path Parameters
The backup policy identifier
The backup policy job identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/jobs/$backup_policy_job_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getBackupPolicyJobOptions := &vpcv1.GetBackupPolicyJobOptions{ BackupPolicyID: &backupPolicyId, ID: &backupPolicyJobId, } backupPolicyJob, response, err := vpcService.GetBackupPolicyJob(getBackupPolicyJobOptions)
GetBackupPolicyJobOptions getBackupPolicyJobOptions = new GetBackupPolicyJobOptions.Builder() .backupPolicyId(backupPolicyId) .id(backupPolicyJobId) .build(); Response<BackupPolicyJob> response = service.getBackupPolicyJob(getBackupPolicyJobOptions).execute(); BackupPolicyJob backupPolicyJobResult = response.getResult();
const params = { backupPolicyId, id: backupPolicyJobId, }; const response = await vpcService.getBackupPolicyJob(params);
get_backup_policy_job_response = service.get_backup_policy_job( backup_policy_id=backup_policy_id, id=backup_policy_job_id, ) backup_policy_job = get_backup_policy_job_response.get_result()
Response
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.Example:
true
If
auto_delete
istrue
, the days after completion that this backup policy job will be deleted. This value may be modifiable in the future.Example:
90
The backup policy plan operated this backup policy job (may be deleted).
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
backup_policy_plan
The date and time that the backup policy job was created
The URL for this backup policy job
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/0fe9e5d8-0a4d-4818-96ec-e99708644a58/jobs/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this backup policy job
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The type of backup policy job.
The enumerated values for this property may expand in the future.
Possible values: [
creation
,deletion
]The resource type
Possible values: [
backup_policy_job
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The source this backup was created from (may be deleted).
The status of the backup policy job.
The enumerated values for this property may expand in the future.
Possible values: [
failed
,running
,succeeded
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The snapshots operated on by this backup policy job (may be deleted).
The date and time that the backup policy job was completed.
If absent, the backup policy job has not yet completed.
Status Code
The backup policy job was retrieved successfully.
A backup policy job with the specified identifier could not be found for the backup policy with the specified identifier.
{ "auto_delete": true, "auto_delete_after": 15, "backup_policy_plan": { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-f1fedf51-f430-4ba4-bd09-29719a91350a/plans/r134-9e1b0b14-21bc-4c83-9f4b-99225fd267b3", "id": "r134-9e1b0b14-21bc-4c83-9f4b-99225fd267b3", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" }, "completed_at": "2022-04-22T20:59:34Z", "created_at": "2022-04-22T20:59:11Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-f1fedf51-f430-4ba4-bd09-29719a91350a/jobs/r134-fc4b7fbc-38af-45d9-9fb6-bf0533acbf90", "id": "r134-fc4b7fbc-38af-45d9-9fb6-bf0533acbf90", "job_type": "creation", "resource_type": "backup_policy_job", "source": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "id": "r134-3ef26463-b769-4794-a4c7-7a231e7648a4", "name": "my-volume-1", "resource_type": "volume" }, "status": "succeeded", "status_reasons": [], "target_snapshots": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::snapshot:r134-5886f8e4-5b0c-4378-9a75-82930936593e", "href": "https://us-south.iaas.cloud.ibm.com/v1/snapshots/r134-5886f8e4-5b0c-4378-9a75-82930936593e", "id": "r134-5886f8e4-5b0c-4378-9a75-82930936593e", "name": "my-backup-plan-1-364d6c2da03e-447d", "resource_type": "snapshot" } ] }
List all plans for a backup policy
This request retrieves all plans for a backup policy. Backup plans provide the backup schedule and deletion triggers.
GET /backup_policies/{backup_policy_id}/plans
Request
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
name
property matching the exact specified name.
curl -X GET "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listBackupPolicyPlansOptions := &vpcv1.ListBackupPolicyPlansOptions{ BackupPolicyID: &backupPolicyId, } backupPolicyPlanCollection, response, err := vpcService.ListBackupPolicyPlans(listBackupPolicyPlansOptions)
ListBackupPolicyPlansOptions listBackupPolicyPlansOptions = new ListBackupPolicyPlansOptions.Builder() .backupPolicyId(backupPolicyId) .build(); Response<BackupPolicyPlanCollection> response = service.listBackupPolicyPlans(listBackupPolicyPlansOptions).execute(); BackupPolicyPlanCollection backupPolicyPlanCollectionResult = response.getResult();
const params = { backupPolicyId, }; const response = await vpcService.listBackupPolicyPlans(params);
list_backup_policy_plans_response = service.list_backup_policy_plans(backup_policy_id) backup_policy_plan_collection = list_backup_policy_plans_response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of backup policy plans
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The backup policy plans were retrieved successfully.
A backup policy with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans?limit=50" }, "limit": 50, "plans": [ { "active": true, "attach_user_tags": [ "my-plan-2" ], "clone_policy": { "max_snapshots": 1, "zones": [] }, "copy_user_tags": true, "created_at": "2022-04-21T15:16:37Z", "cron_spec": "45 * * * *", "deletion_trigger": { "delete_after": 5 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "id": "r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "lifecycle_state": "stable", "name": "my-backup-plan-2", "remote_region_policies": [], "resource_type": "backup_policy_plan" } ], "total_count": 1 }
Create a plan for a backup policy
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.
POST /backup_policies/{backup_policy_id}/plans
Request
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The backup policy plan prototype object
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
Indicates whether the plan is active.
Default:
true
User tags to attach to each backup (snapshot) created by this plan. If unspecified, no user tags will be attached.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
Default:
true
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.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions.
curl -X POST "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-backup-plan-2", "attach_user_tags": ["my-plan-2"], "cron_spec": "45 * * * *", "deletion_trigger": {"delete_after": 5} }'
backupPolicyPlanDeletionTriggerPrototypeModel := &vpcv1.BackupPolicyPlanDeletionTriggerPrototype{ DeleteAfter: []int{int64(20)}[0], DeleteOverCount: []int{int64(20)}[0], } createBackupPolicyPlanOptions := &vpcv1.CreateBackupPolicyPlanOptions{ BackupPolicyID: &backupPolicyId, CronSpec: []string{"*/5 1,2,3 * * *"}[0], AttachUserTags: []string{"my-daily-backup-plan"}, DeletionTrigger: backupPolicyPlanDeletionTriggerPrototypeModel, Name: []string{"my-policy-plan"}[0], } backupPolicyPlan, response, err := vpcService.CreateBackupPolicyPlan(createBackupPolicyPlanOptions)
BackupPolicyPlanDeletionTriggerPrototype backupPolicyPlanDeletionTriggerPrototypeModel = new BackupPolicyPlanDeletionTriggerPrototype.Builder() .deleteAfter(Long.valueOf("20")) .deleteOverCount(Long.valueOf("20")) .build(); CreateBackupPolicyPlanOptions createBackupPolicyPlanOptions = new CreateBackupPolicyPlanOptions.Builder() .backupPolicyId(backupPolicyId) .cronSpec("*/5 1,2,3 * * *") .attachUserTags(new java.util.ArrayList<String>(java.util.Arrays.asList("my-daily-backup-plan"))) .deletionTrigger(backupPolicyPlanDeletionTriggerPrototypeModel) .name("my-policy-plan") .build(); Response<BackupPolicyPlan> response = service.createBackupPolicyPlan(createBackupPolicyPlanOptions).execute(); BackupPolicyPlan backupPolicyPlanResult = response.getResult();
const backupPolicyPlanDeletionTriggerPrototypeModel = { delete_after: 20, delete_over_count: 20, }; const params = { backupPolicyId, cronSpec: '*/5 1,2,3 * * *', attachUserTags: ['my-daily-backup-plan'], deletionTrigger: backupPolicyPlanDeletionTriggerPrototypeModel, name: 'my-policy-plan', }; const response = await vpcService.createBackupPolicyPlan(params);
backup_policy_plan_deletion_trigger_prototype_model = { 'delete_after': 20, 'delete_over_count': 20 } create_backup_policy_plan_response = service.create_backup_policy_plan( backup_policy_id=backup_policy_id, cron_spec='*/5 1,2,3 * * *', attach_user_tags=['my-daily-backup-plan'], deletion_trigger=backup_policy_plan_deletion_trigger_prototype_model, name='my-policy-plan', ) backup_policy_plan = create_backup_policy_plan_response.get_result()
Response
Indicates whether the plan is active.
The user tags to attach to backups (snapshots) created by this plan.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
The date and time that the backup policy plan was created
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The lifecycle state of this backup policy plan
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions.
Possible values: number of items ≥ 0, contains only unique items
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The backup policy plan was created successfully.
An invalid backup policy plan prototype object was provided.
A backup policy with the specified identifier could not be found.
The backup policy plan prototype object specified an encryption key that cannot be used in its current state.
{ "active": true, "attach_user_tags": [ "my-plan-2" ], "clone_policy": { "max_snapshots": 1, "zones": [] }, "copy_user_tags": true, "created_at": "2022-04-21T15:16:37Z", "cron_spec": "45 * * * *", "deletion_trigger": { "delete_after": 5 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "id": "r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "lifecycle_state": "pending", "name": "my-backup-plan-2", "remote_region_policies": [], "resource_type": "backup_policy_plan" }
Delete a backup policy plan
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.
DELETE /backup_policies/{backup_policy_id}/plans/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The backup policy identifier
The backup policy plan identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans/$backup_policy_plan_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteBackupPolicyPlanOptions := &vpcv1.DeleteBackupPolicyPlanOptions{ BackupPolicyID: &backupPolicyId, ID: &backupPolicyPlanId, } backupPolicyPlan, response, err := vpcService.DeleteBackupPolicyPlan(deleteBackupPolicyPlanOptions)
DeleteBackupPolicyPlanOptions deleteBackupPolicyPlanOptions = new DeleteBackupPolicyPlanOptions.Builder() .backupPolicyId(backupPolicyId) .id(backupPolicyPlanId) .build(); Response<BackupPolicyPlan> response = service.deleteBackupPolicyPlan(deleteBackupPolicyPlanOptions).execute(); BackupPolicyPlan backupPolicyPlanResult = response.getResult();
const params = { backupPolicyId, id: backupPolicyPlanId, }; const response = await vpcService.deleteBackupPolicyPlan(params);
delete_backup_policy_plan_response = service.delete_backup_policy_plan( backup_policy_id=backup_policy_id, id=backup_policy_plan_id, ) backup_policy_plan = delete_backup_policy_plan_response.get_result()
Response
Indicates whether the plan is active.
The user tags to attach to backups (snapshots) created by this plan.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
The date and time that the backup policy plan was created
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The lifecycle state of this backup policy plan
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions.
Possible values: number of items ≥ 0, contains only unique items
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The backup policy plan deletion request was accepted.
A backup policy plan with the specified identifier could not be found for the policy plan with the specified identifier.
The provided
If-Match
value does not match the current ETag value of the backup policy plan.
{ "active": true, "attach_user_tags": [ "my-plan-2" ], "clone_policy": { "max_snapshots": 1, "zones": [] }, "copy_user_tags": true, "created_at": "2022-04-21T15:16:37Z", "cron_spec": "45 * * * *", "deletion_trigger": { "delete_after": 5 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "id": "r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "lifecycle_state": "deleting", "name": "my-backup-plan-2", "remote_region_policies": [], "resource_type": "backup_policy_plan" }
Retrieve a backup policy plan
This request retrieves a single backup policy plan specified by the identifier in the URL.
GET /backup_policies/{backup_policy_id}/plans/{id}
Request
Path Parameters
The backup policy identifier
The backup policy plan identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans/$backup_policy_plan_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getBackupPolicyPlanOptions := &vpcv1.GetBackupPolicyPlanOptions{ BackupPolicyID: &backupPolicyId, ID: &backupPolicyPlanId, } backupPolicyPlan, response, err := vpcService.GetBackupPolicyPlan(getBackupPolicyPlanOptions)
GetBackupPolicyPlanOptions getBackupPolicyPlanOptions = new GetBackupPolicyPlanOptions.Builder() .backupPolicyId(backupPolicyId) .id(backupPolicyPlanId) .build(); Response<BackupPolicyPlan> response = service.getBackupPolicyPlan(getBackupPolicyPlanOptions).execute(); BackupPolicyPlan backupPolicyPlanResult = response.getResult();
const params = { backupPolicyId, id: backupPolicyPlanId, }; const response = await vpcService.getBackupPolicyPlan(params);
get_backup_policy_plan_response = service.get_backup_policy_plan( backup_policy_id=backup_policy_id, id=backup_policy_plan_id, ) backup_policy_plan = get_backup_policy_plan_response.get_result()
Response
Indicates whether the plan is active.
The user tags to attach to backups (snapshots) created by this plan.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
The date and time that the backup policy plan was created
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The lifecycle state of this backup policy plan
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions.
Possible values: number of items ≥ 0, contains only unique items
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The backup policy plan was retrieved successfully.
A backup policy plan with the specified identifier could not be found for the backup policy with the specified identifier.
{ "active": true, "attach_user_tags": [ "my-plan-2" ], "clone_policy": { "max_snapshots": 1, "zones": [] }, "copy_user_tags": true, "created_at": "2022-04-21T15:16:37Z", "cron_spec": "45 * * * *", "deletion_trigger": { "delete_after": 5 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "id": "r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "lifecycle_state": "stable", "name": "my-backup-plan-2", "remote_region_policies": [], "resource_type": "backup_policy_plan" }
Update a backup policy plan
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.
PATCH /backup_policies/{backup_policy_id}/plans/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The backup policy identifier
The backup policy plan identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The backup policy plan patch
Indicates whether the plan is active.
The user tags to attach to backups (snapshots) created by this plan. Updating this value does not change the user tags for backups that have already been created by this plan.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The name for this backup policy plan. The name must not be used by another plan for the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions (replacing any existing policies).
curl -X PATCH "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans/$backup_policy_plan_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "copy_user_tags": "false" }'
backupPolicyPlanPatchModel := &vpcv1.BackupPolicyPlanPatch{ Name: []string{"my-policy-plan-updated"}[0], } backupPolicyPlanPatchModelAsPatch, asPatchErr := backupPolicyPlanPatchModel.AsPatch() updateBackupPolicyPlanOptions := &vpcv1.UpdateBackupPolicyPlanOptions{ BackupPolicyID: &backupPolicyId, ID: &backupPolicyPlanId, BackupPolicyPlanPatch: backupPolicyPlanPatchModelAsPatch, } backupPolicyPlan, response, err := vpcService.UpdateBackupPolicyPlan(updateBackupPolicyPlanOptions)
BackupPolicyPlanPatch backupPolicyPlanPatchModel = new BackupPolicyPlanPatch.Builder() .name("my-policy-plan-updated") .build(); Map<String, Object> backupPolicyPlanPatchModelAsPatch = backupPolicyPlanPatchModel.asPatch(); UpdateBackupPolicyPlanOptions updateBackupPolicyPlanOptions = new UpdateBackupPolicyPlanOptions.Builder() .backupPolicyId(backupPolicyId) .id(backupPolicyPlanId) .backupPolicyPlanPatch(backupPolicyPlanPatchModelAsPatch) .build(); Response<BackupPolicyPlan> response = service.updateBackupPolicyPlan(updateBackupPolicyPlanOptions).execute(); BackupPolicyPlan backupPolicyPlanResult = response.getResult();
const params = { backupPolicyId, id: backupPolicyPlanId, name: 'my-policy-plan-updated', }; const response = await vpcService.updateBackupPolicyPlan(params);
backup_policy_plan_patch_model = { 'name': 'my-policy-plan-updated' } update_backup_policy_plan_response = service.update_backup_policy_plan( backup_policy_id=backup_policy_id, id=backup_policy_plan_id, backup_policy_plan_patch=backup_policy_plan_patch_model, ) backup_policy_plan = update_backup_policy_plan_response.get_result()
Response
Indicates whether the plan is active.
The user tags to attach to backups (snapshots) created by this plan.
Possible values: 0 ≤ number of items ≤ 1000, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewIndicates whether to copy the source's user tags to the created backups (snapshots).
The date and time that the backup policy plan was created
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.
Possible values: 9 ≤ length ≤ 63, Value must match regular expression
^(((\d+,)+\d+|([\d\*]+(\/|-)\d+)|\d+|\*) ?){5}$
Example:
30 */2 * * 1-5
The URL for this backup policy plan
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The unique identifier for this backup policy plan
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178
The lifecycle state of this backup policy plan
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this backup policy plan. The name is unique across all plans in the backup policy.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-policy-plan
The policies for additional backups in remote regions.
Possible values: number of items ≥ 0, contains only unique items
The resource type
Possible values: [
backup_policy_plan
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The backup policy plan was updated successfully.
An invalid backup policy plan patch was provided.
A backup policy plan with the specified identifier could not be found for the backup policy with the specified identifier.
The specified encryption key cannot be used in its current state.
The provided
If-Match
value does not match the current ETag value of the backup policy plan.
{ "active": true, "attach_user_tags": [ "my-plan-2" ], "clone_policy": { "max_snapshots": 1, "zones": [] }, "copy_user_tags": false, "created_at": "2022-04-21T15:16:37Z", "cron_spec": "45 * * * *", "deletion_trigger": { "delete_after": 5 }, "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "id": "r134-6da51cfe-6f7b-4638-a6ba-00e9c327b178", "lifecycle_state": "stable", "name": "my-backup-plan-2", "remote_region_policies": [], "resource_type": "backup_policy_plan" }
Delete a backup policy
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.
DELETE /backup_policies/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteBackupPolicyOptions := &vpcv1.DeleteBackupPolicyOptions{ ID: &backupPolicyId, } backupPolicy, response, err := vpcService.DeleteBackupPolicy(deleteBackupPolicyOptions)
DeleteBackupPolicyOptions deleteBackupPolicyOptions = new DeleteBackupPolicyOptions.Builder() .id(backupPolicyId) .build(); Response<BackupPolicy> response = service.deleteBackupPolicy(deleteBackupPolicyOptions).execute(); BackupPolicy backupPolicyResult = response.getResult();
const params = { id: backupPolicyId, }; const response = await vpcService.deleteBackupPolicy(params);
delete_backup_policy_response = service.delete_backup_policy( id=backup_policy_id, ) backup_policy = delete_backup_policy_response.get_result()
Response
The date and time that the backup policy was created
The CRN for this backup policy
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this backup policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The unique identifier for this backup policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The lifecycle state of the backup policy
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
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.
Possible values: [
instance
,volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe name for this backup policy. The name is unique across all backup policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
The plans for the backup policy.
The resource group for this backup policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
backup_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The scope for this backup policy.
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.
The included content for backups created using this policy:
boot_volume
: Include the instance's boot volume.data_volumes
: Include the instance's data volumes.
The enumerated values for this property may expand in the future.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
One of
Status Code
The backup policy deletion request was accepted.
A backup policy with the specified identifier could not be found.
The provided
If-Match
value does not match the current ETag value of the backup policy.
{ "created_at": "2022-04-21T15:06:03.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "included_content": [ "data_volume" ], "lifecycle_state": "deleting", "match_resource_type": "volume", "match_user_tags": [ "my-tag-1", "my-tag-2" ], "name": "my-backup-policy", "plans": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "id": "r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" } ], "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "backup_policy", "scope": { "crn": "crn:v1:bluemix:public:enterprise::a/aa2432b1fa4d4ace891e9b80fc104e34::enterprise:ebc2b430240943458b9e91e1432cfcce", "id": "ebc2b430240943458b9e91e1432cfcce", "resource_type": "enterprise" } }
Retrieve a backup policy
This request retrieves a single backup policy specified by the identifier in the URL.
GET /backup_policies/{id}
Request
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getBackupPolicyOptions := &vpcv1.GetBackupPolicyOptions{ ID: &backupPolicyId, } backupPolicy, response, err := vpcService.GetBackupPolicy(getBackupPolicyOptions)
GetBackupPolicyOptions getBackupPolicyOptions = new GetBackupPolicyOptions.Builder() .id(backupPolicyId) .build(); Response<BackupPolicy> response = service.getBackupPolicy(getBackupPolicyOptions).execute(); BackupPolicy backupPolicyResult = response.getResult();
const params = { id: backupPolicyId, }; const response = await vpcService.getBackupPolicy(params);
get_backup_policy_response = service.get_backup_policy(id=backup_policy_id) backup_policy = get_backup_policy_response.get_result()
Response
The date and time that the backup policy was created
The CRN for this backup policy
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this backup policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The unique identifier for this backup policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The lifecycle state of the backup policy
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
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.
Possible values: [
instance
,volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe name for this backup policy. The name is unique across all backup policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
The plans for the backup policy.
The resource group for this backup policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
backup_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The scope for this backup policy.
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.
The included content for backups created using this policy:
boot_volume
: Include the instance's boot volume.data_volumes
: Include the instance's data volumes.
The enumerated values for this property may expand in the future.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
One of
Status Code
The backup policy was retrieved successfully.
A backup policy with the specified identifier could not be found.
{ "created_at": "2022-04-21T15:06:03.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "included_content": [ "data_volume" ], "lifecycle_state": "stable", "match_resource_type": "volume", "match_user_tags": [ "my-tag-1", "my-tag-2" ], "name": "my-backup-policy", "plans": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "id": "r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" } ], "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "backup_policy", "scope": { "crn": "crn:v1:bluemix:public:enterprise::a/aa2432b1fa4d4ace891e9b80fc104e34::enterprise:ebc2b430240943458b9e91e1432cfcce", "id": "ebc2b430240943458b9e91e1432cfcce", "resource_type": "enterprise" } }
Update a backup policy
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.
PATCH /backup_policies/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The backup policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The backup policy patch
The included content for backups created using this policy:
boot_volume
: Include the instance's boot volume.data_volumes
: Include the instance's data volumes.
Allowable values: [
boot_volume
,data_volumes
]Possible values: number of items ≥ 1, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The user tags this backup policy will apply to (replacing any existing tags). Resources that have both a matching user tag and a matching type will be subject to the backup policy.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe name for this backup policy. The name must not be used by another backup policy in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
curl -X PATCH "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "match_user_tags": [ "my-tag-1", "my-tag-2", "my-tag-3" ] }'
backupPolicyPatchModel := &vpcv1.BackupPolicyPatch{ Name: []string{"my-backup-policy-updated"}[0], } backupPolicyPatchModelAsPatch, asPatchErr := backupPolicyPatchModel.AsPatch() updateBackupPolicyOptions := &vpcv1.UpdateBackupPolicyOptions{ ID: &backupPolicyId, BackupPolicyPatch: backupPolicyPatchModelAsPatch, } backupPolicy, response, err := vpcService.UpdateBackupPolicy(updateBackupPolicyOptions)
BackupPolicyPatch backupPolicyPatchModel = new BackupPolicyPatch.Builder() .name("my-backup-policy-updated") .build(); Map<String, Object> backupPolicyPatchModelAsPatch = backupPolicyPatchModel.asPatch(); UpdateBackupPolicyOptions updateBackupPolicyOptions = new UpdateBackupPolicyOptions.Builder() .id(backupPolicyId) .backupPolicyPatch(backupPolicyPatchModelAsPatch) .build(); Response<BackupPolicy> response = service.updateBackupPolicy(updateBackupPolicyOptions).execute(); BackupPolicy backupPolicyResult = response.getResult();
const params = { id: backupPolicyId, name: 'my-backup-policy-updated', }; const response = await vpcService.updateBackupPolicy(params);
backup_policy_patch_model = { 'name': 'my-backup-policy-updated' } update_backup_policy_response = service.update_backup_policy( id=backup_policy_id, backup_policy_patch=backup_policy_patch_model, ) backup_policy = update_backup_policy_response.get_result()
Response
The date and time that the backup policy was created
The CRN for this backup policy
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this backup policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The unique identifier for this backup policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-076191ba-49c2-4763-94fd-c70de73ee2e6
The lifecycle state of the backup policy
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
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.
Possible values: [
instance
,volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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.
Possible values: 1 ≤ number of items ≤ 1000, contains only unique items, 1 ≤ length ≤ 128, Value must match regular expression
^[A-Za-z0-9:_ .-]+$
Examples:ViewThe name for this backup policy. The name is unique across all backup policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-backup-policy
The plans for the backup policy.
The resource group for this backup policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
backup_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The scope for this backup policy.
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.
The included content for backups created using this policy:
boot_volume
: Include the instance's boot volume.data_volumes
: Include the instance's data volumes.
The enumerated values for this property may expand in the future.
Possible values: number of items ≥ 1, contains only unique items
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.
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
One of
Status Code
The backup policy was updated successfully.
An invalid backup policy patch was provided.
A backup policy with the specified identifier could not be found.
The provided
If-Match
value does not match the current ETag value of the backup policy.
{ "created_at": "2022-04-21T15:06:03.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::backup-policy:r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "id": "r134-076191ba-49c2-4763-94fd-c70de73ee2e6", "included_content": [ "data_volume" ], "lifecycle_state": "stable", "match_resource_type": "volume", "match_user_tags": [ "my-tag-1", "my-tag-2", "my-tag-3" ], "name": "my-backup-policy", "plans": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/backup_policies/r134-076191ba-49c2-4763-94fd-c70de73ee2e6/plans/r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "id": "r134-4d6074c4-3811-4bb3-af4a-1fd6cb38d6fe", "name": "my-backup-plan-1", "resource_type": "backup_policy_plan" } ], "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "backup_policy", "scope": { "crn": "crn:v1:bluemix:public:enterprise::a/aa2432b1fa4d4ace891e9b80fc104e34::enterprise:ebc2b430240943458b9e91e1432cfcce", "id": "ebc2b430240943458b9e91e1432cfcce", "resource_type": "enterprise" } }
List all regions
This request lists all regions. Each region is a separate geographic area that contains multiple isolated zones. Resources can be provisioned into one or more zones in a region. Each zone is isolated, but connected to other zones in the same region with low-latency and high-bandwidth links. Regions represent the top-level of fault isolation available. Resources deployed within a single region also benefit from the low latency afforded by geographic proximity.
GET /regions
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/regions?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listRegionsOptions := &vpcv1.ListRegionsOptions{} regions, response, err := gen2.ListRegions(listRegionsOptions)
ListRegionsOptions listRegionsOptions = new ListRegionsOptions(); Response<RegionCollection> response = service.listRegions(listRegionsOptions).execute(); RegionCollection regionCollection = response.getResult();
const response = await vpcService.listRegions();
response = service.list_regions()
Response
Collection of regions
Status Code
The regions were retrieved successfully.
{ "regions": [ { "endpoint": "https://us-south.iaas.cloud.ibm.com", "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south", "status": "available" }, { "endpoint": "https://eu-de.iaas.cloud.ibm.com", "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/eu-de", "name": "eu-de", "status": "available" } ] }
Retrieve a region
This request retrieves a single region specified by the name in the URL.
GET /regions/{name}
Request
Path Parameters
The region name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/regions/$region_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getRegionOptions := &vpcv1.GetRegionOptions{} getRegionOptions.SetName(name) region, response, err := vpcService.GetRegion(getRegionOptions)
GetRegionOptions getRegionOptions = new GetRegionOptions.Builder() .name(regionName) .build(); Response<Region> response = service.getRegion(getRegionOptions).execute(); Region region = response.getResult();
const response = await vpcService.getRegion({ regionName });
response = service.get_region(name)
Response
The API endpoint for this region.
The URL for this region
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south
The globally unique name for this region
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
The availability status of this region
Possible values: [
available
,unavailable
]
Status Code
The region was retrieved successfully.
A region with the specified name could not be found.
{ "endpoint": "https://us-south.iaas.cloud.ibm.com", "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south", "status": "available" }
List all zones in a region
This request lists all zones in a region. Zones represent logically-isolated data centers with high-bandwidth and low-latency interconnects to other zones in the same region. Faults in a zone do not affect other zones.
GET /regions/{region_name}/zones
Request
Path Parameters
The region name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/regions/$region_name/zones?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listZonesOptions := &vpcv1.ListRegionZonesOptions{} listZonesOptions.SetRegionName(regionName) zones, response, err := vpcService.ListRegionZones(listZonesOptions)
ListRegionZonesOptions listRegionZonesOptions = new ListRegionZonesOptions.Builder() .regionName(regionName) .build(); Response<ZoneCollection> response = service.listRegionZones(listRegionZonesOptions).execute(); ZoneCollection zoneCollection = response.getResult();
const response = await vpcService.listRegionZones({ regionName });
response = service.list_region_zones(region_name)
Response
Collection of zones
Status Code
The zones were retrieved successfully.
A region with the specified name could not be found.
{ "zones": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1", "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" }, "status": "available" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-2", "name": "us-south-2", "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" }, "status": "available" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-3", "name": "us-south-3", "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" }, "status": "available" } ] }
Retrieve a zone
This request retrieves a single zone specified by the region and zone names in the URL.
GET /regions/{region_name}/zones/{name}
Request
Path Parameters
The region name
The zone name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/regions/$region_name/zones/$zone_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getZoneOptions := &vpcv1.GetRegionZoneOptions{} getZoneOptions.SetRegionName(regionName) getZoneOptions.SetZoneName(zoneName) zone, response, err := vpcService.GetRegionZone(getZoneOptions)
GetRegionZoneOptions getRegionZoneOptions = new GetRegionZoneOptions.Builder() .regionName(regionName) .zoneName(zoneName) .build(); Response<Zone> response = service.getRegionZone(getRegionZoneOptions).execute(); Zone zone = response.getResult();
const response = await vpcService.getRegionZone({ region: regionName, zone: zoneName, });
response = service.get_region_zone(region_name, zone_name)
Response
The URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
The region this zone resides in
The URL for this region
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south
The globally unique name for this region
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south
region
The availability status of this zone.
Possible values: [
available
,impaired
,unavailable
]
Status Code
The zone was retrieved successfully.
A zone with the specified name could not be found.
{ "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1", "region": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south", "name": "us-south" }, "status": "available" }
List all virtual network interfaces
This request lists all virtual network interfaces in the region. A virtual network interface is a logical abstraction of a virtual network interface in a subnet, and may be attached to a target resource.
The virtual network interfaces will be sorted by their created_at
property values, with
newest virtual network interfaces first. Virtual network interfaces with identical
created_at
property values will in turn be sorted by ascending name
property values.
GET /virtual_network_interfaces
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVirtualNetworkInterfacesOptions := &vpcv1.ListVirtualNetworkInterfacesOptions{} virtualNetworkInterfaceCollection, response, err := vpcService.ListVirtualNetworkInterfaces(listVirtualNetworkInterfacesOptions)
ListVirtualNetworkInterfacesOptions listVirtualNetworkInterfacesOptions = new ListVirtualNetworkInterfacesOptions.Builder() .build(); Response<VirtualNetworkInterfaceCollection> response = vpcService.listVirtualNetworkInterfaces(listVirtualNetworkInterfacesOptions).execute(); VirtualNetworkInterfaceCollection virtualNetworkInterfaceCollectionResult = response.getResult();
const response = await vpcService.listVirtualNetworkInterfaces();
response = vpc_service.list_virtual_network_interfaces() virtual_network_interface_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
Collection of virtual network interfaces
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces?start=d3e721fd-c988-4670-9927-dbd5e7b07fc6&limit=20
next
Status Code
The virtual network interfaces were retrieved successfully.
{ "$ref": "#/components/schemas/VirtualNetworkInterfaceCollection/example" }
Create a virtual network interface
This request creates a new virtual network interface from a virtual network interface prototype object. The prototype object is structured in the same way as a retrieved virtual network interface, and contains the information necessary to create the new virtual network interface.
POST /virtual_network_interfaces
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.create
is.virtual-network-interface.virtual-network-interface.attach
Generated for each reserved IP being attached to the virtual network interface
is.subnet.reserved-ip.create
Generated for each reserved IP created
is.subnet.subnet.update
Generated for each reserved IP created
is.subnet.reserved-ip.attach
Generated for each reserved IP being attached to the virtual network interface
is.security-group.security-group.attach
Generated for each security group being attached to the virtual network interface
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The virtual network interface prototype object
Indicates whether source IP spoofing is allowed on this interface. If
false
, source IP spoofing is prevented on this interface. Iftrue
, source IP spoofing is allowed on this interface.Default:
false
Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deleted. Must befalse
if the virtual network interface is unbound.Default:
false
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.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Default:
true
Example:
true
Additional IP addresses to bind to the virtual network interface. Each item may be either a reserved IP identity, or a reserved IP prototype object which will be used to create a new reserved IP. All IP addresses must be in the primary IP's subnet.
If reserved IP identities are provided, the specified reserved IPs must be unbound.
If reserved IP prototype objects with addresses are provided, the addresses must be available on the virtual network interface's subnet. For any prototype objects that do not specify an address, an available address on the subnet will be automatically selected and reserved.
Examples:Viewips
The name for this virtual network interface. The name must not be used by another virtual network interface in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words. Names beginning with
ibm-
are reserved for provider-owned resources, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The primary IP address to bind to the virtual network interface. May be either a reserved IP identity, or a reserved IP prototype object which will be used to create a new reserved IP.
If a reserved IP identity is provided, the specified reserved IP must be unbound.
If a reserved IP prototype object with an address is provided, the address must be available on the virtual network interface's subnet. If no address is specified, an available address on the subnet will be automatically selected and reserved.
primary_ip
The resource group to use. If unspecified, the account's default resource group will be used.
The security groups to use for this virtual network interface. If unspecified, the default security group of the VPC for the subnet is used.
Possible values: contains only unique items
Examples:Viewsecurity_groups
The associated subnet. Required if
primary_ip
does not specify a reserved IP identity.The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
subnet
curl -X POST "$vpc_api_endpoint/v1/virtual_network_interfaces?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-network-interface", "subnet": { "id": "8722d01c-9c78-4555-82b5-53ad1266f959" } }'
subnetIdentityModel := &vpcv1.SubnetIdentityByID{ ID: &subnetId, } createVirtualNetworkInterfaceOptions := &vpcv1.CreateVirtualNetworkInterfaceOptions{ Name: &[]string{"my-virtual-network-interface"}[0], Subnet: subnetIdentityModel, } virtualNetworkInterface, response, err := vpcService.CreateVirtualNetworkInterface(createVirtualNetworkInterfaceOptions)
SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); CreateVirtualNetworkInterfaceOptions createVirtualNetworkInterfaceOptions = new CreateVirtualNetworkInterfaceOptions.Builder() .name("my-virtual-network-interface") .subnet(subnetIdentityModel) .build(); Response<VirtualNetworkInterface> response = vpcService.createVirtualNetworkInterface(createVirtualNetworkInterfaceOptions).execute(); VirtualNetworkInterface virtualNetworkInterface = response.getResult();
const subnetIdentityModel = { id: subnetID, }; const params = { name: 'my-virtual-network-interface', subnet: subnetIdentityModel, }; const response = await vpcService.createVirtualNetworkInterface(params);
subnet_identity_model = {} subnet_identity_model['id'] = subnet_id response = vpc_service.create_virtual_network_interface( name='my-virtual-network-interface', subnet=subnet_identity_model, ) virtual_network_interface = response.get_result()
Response
Indicates whether source IP spoofing is allowed on this interface. If
false
, source IP spoofing is prevented on this interface. Iftrue
, source IP spoofing is allowed on this interface.Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deletedThe date and time that the virtual network interface was created
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
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.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Example:
true
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The reserved IPs bound to this virtual network interface.
May be empty when
lifecycle_state
ispending
.Possible values: number of items ≥ 0
The lifecycle state of the virtual network interface
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The reserved IP for this virtual network interface.
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource group for this virtual network interface
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups for this virtual network interface.
Possible values: number of items ≥ 1
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The VPC this virtual network interface resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual network interface resides in.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The MAC address of the virtual network interface. May be absent if
lifecycle_state
ispending
.Possible values: length = 17, Value must match regular expression
^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:4D:45:45:4D
The target of this virtual network interface.
If absent, this virtual network interface is not attached to a target.
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Status Code
The virtual network interface was created successfully.
An invalid virtual network interface prototype object was provided.
{ "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2019-01-31T03:42:32.993Z", "crn": "crn:[...]", "enable_infrastructure_nat": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6A", "name": "my-virtual-network-interface", "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "my-security-group" } ], "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a virtual network interface
This request deletes a virtual network interface. This operation cannot be reversed. For this request to succeed, the virtual network interface must not be required by another resource, such as the primary network attachment for an instance.
DELETE /virtual_network_interfaces/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.delete
is.virtual-network-interface.virtual-network-interface.detach
Generated for resource being detached from the virtual network interface:
- reserved IPs
- security groups
is.subnet.reserved-ip.delete
Generated for each reserved IP that had
auto_delete
set totrue
is.subnet.subnet.update
Generated for each reserved IP that had
auto_delete
set totrue
is.floating-ip.floating-ip.detach
Generated for each floating IP being detached from the virtual network interface
is.subnet.reserved-ip.detach
Generated for each reserved IP being detached from the virtual network interface
is.security-group.security-group.detach
Generated for each security group being detached from the virtual network interface
is.flow-log-collector.flow-log-collector.delete
Generated when a flow log collector that had
auto_delete
set totrue
was attached to the virtual network interfaceis.flow-log-collector.flow-log-collector.detach
Generated if a flow log collector is detached from the virtual network interface
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVirtualNetworkInterfacesOptions := &vpcv1.DeleteVirtualNetworkInterfacesOptions{ ID: &virtualNetworkInterfaceId, } virtualNetworkInterface, response, err := vpcService.DeleteVirtualNetworkInterfaces(deleteVirtualNetworkInterfacesOptions)
DeleteVirtualNetworkInterfaceOptions deleteVirtualNetworkInterfaceOptions = new DeleteVirtualNetworkInterfaceOptions.Builder() .id(virtualNetworkInterfaceId) .build(); Response<void> response = vpcService.DeleteVirtualNetworkInterface(deleteVirtualNetworkInterfaceOptions).execute();
const params = { id: virtualNetworkInterfaceId, }; const response = await vpcService.deleteVirtualNetworkInterfaces(params);
response = vpc_service.delete_virtual_network_interfaces( id=virtualNetworkInterfaceId, )
Retrieve a virtual network interface
This request retrieves a single virtual network interface specified by the identifier in the URL.
GET /virtual_network_interfaces/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVirtualNetworkInterfaceOptions := &vpcv1.GetVirtualNetworkInterfaceOptions{ ID: &virtualNetworkInterfaceId, } virtualNetworkInterface, response, err := vpcService.GetVirtualNetworkInterface(getVirtualNetworkInterfaceOptions)
GetVirtualNetworkInterfaceOptions getVirtualNetworkInterfaceOptions = new GetVirtualNetworkInterfaceOptions.Builder() .id(virtualNetworkInterfaceId) .build(); Response<VirtualNetworkInterface> response = vpcService.getVirtualNetworkInterface(getVirtualNetworkInterfaceOptions).execute(); VirtualNetworkInterface virtualNetworkInterface = response.getResult();
const params = { id: virtualNetworkInterfaceId, }; const response = await vpcService.getVirtualNetworkInterface(params);
response = vpc_service.get_virtual_network_interface( id=virtualNetworkInterfaceId, ) virtual_network_interface = response.get_result()
Response
Indicates whether source IP spoofing is allowed on this interface. If
false
, source IP spoofing is prevented on this interface. Iftrue
, source IP spoofing is allowed on this interface.Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deletedThe date and time that the virtual network interface was created
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
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.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Example:
true
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The reserved IPs bound to this virtual network interface.
May be empty when
lifecycle_state
ispending
.Possible values: number of items ≥ 0
The lifecycle state of the virtual network interface
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The reserved IP for this virtual network interface.
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource group for this virtual network interface
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups for this virtual network interface.
Possible values: number of items ≥ 1
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The VPC this virtual network interface resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual network interface resides in.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The MAC address of the virtual network interface. May be absent if
lifecycle_state
ispending
.Possible values: length = 17, Value must match regular expression
^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:4D:45:45:4D
The target of this virtual network interface.
If absent, this virtual network interface is not attached to a target.
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Status Code
The virtual network interface was retrieved successfully.
The specified virtual network interface could not be found.
{ "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2019-01-31T03:42:32.993Z", "crn": "crn:[...]", "enable_infrastructure_nat": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6A", "name": "my-virtual-network-interface", "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "my-security-group" } ], "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a virtual network interface
This request updates a virtual network interface with the information in a provided virtual network interface patch. The virtual network interface patch object is structured in the same way as a retrieved virtual network interface and contains only the information to be updated.
PATCH /virtual_network_interfaces/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The virtual network interface patch
Indicates whether source IP spoofing is allowed on this interface.
Must be
false
iftarget
is a file share mount target.Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deleted. Must befalse
if the virtual network interface is unbound.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.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Example:
true
The name for this virtual network interface. The name must not be used by another virtual network interface in the region. Names beginning with
ibm-
are reserved for provider-owned resources, and are not allowed.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
curl -X PATCH "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-network-interface-updated" }'
virtualNetworkInterfacePatchModel := &vpcv1.VirtualNetworkInterfacePatch{ Name: &[]string{"my-virtual-network-interface-updated"}[0], } virtualNetworkInterfacePatchModelAsPatch, asPatchErr := virtualNetworkInterfacePatchModel.AsPatch() updateVirtualNetworkInterfaceOptions := &vpcv1.UpdateVirtualNetworkInterfaceOptions{ ID: &virtualNetworkInterfaceId, VirtualNetworkInterfacePatch: virtualNetworkInterfacePatchModelAsPatch, } virtualNetworkInterface, response, err := vpcService.UpdateVirtualNetworkInterface(updateVirtualNetworkInterfaceOptions)
VirtualNetworkInterfacePatch virtualNetworkInterfacePatchModel = new VirtualNetworkInterfacePatch.Builder() .name("my-virtual-network-interface-updated") .build(); Map<String, Object> virtualNetworkInterfacePatchModelAsPatch = virtualNetworkInterfacePatchModel.asPatch(); UpdateVirtualNetworkInterfaceOptions updateVirtualNetworkInterfaceOptions = new UpdateVirtualNetworkInterfaceOptions.Builder() .id(virtualNetworkInterfaceId) .virtualNetworkInterfacePatch(virtualNetworkInterfacePatchModelAsPatch) .build(); Response<VirtualNetworkInterface> response = vpcService.updateVirtualNetworkInterface(updateVirtualNetworkInterfaceOptions).execute(); VirtualNetworkInterface virtualNetworkInterface = response.getResult();
const params = { id: virtualNetworkInterfaceId, name: 'my-virtual-network-interface-updated', }; const response = await vpcService.updateVirtualNetworkInterface(params);
virtual_network_interface_patch_model = { 'name': 'my-virtual-network-interface-updated' } response = vpc_service.update_virtual_network_interface( id=virtualNetworkInterfaceId, virtual_network_interface_patch=virtual_network_interface_patch_model, ) virtual_network_interface = response.get_result()
Response
Indicates whether source IP spoofing is allowed on this interface. If
false
, source IP spoofing is prevented on this interface. Iftrue
, source IP spoofing is allowed on this interface.Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deletedThe date and time that the virtual network interface was created
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
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.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Example:
true
The URL for this virtual network interface
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/virtual_network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0767-fa41aecb-4f21-423d-8082-630bfba1e1d9
The reserved IPs bound to this virtual network interface.
May be empty when
lifecycle_state
ispending
.Possible values: number of items ≥ 0
The lifecycle state of the virtual network interface
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The reserved IP for this virtual network interface.
Examples:ViewThe 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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
primary_ip
The resource group for this virtual network interface
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups for this virtual network interface.
Possible values: number of items ≥ 1
The associated subnet
Examples:ViewThe CRN for this subnet
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The URL for this subnet
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
subnet
The VPC this virtual network interface resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this virtual network interface resides in.
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The MAC address of the virtual network interface. May be absent if
lifecycle_state
ispending
.Possible values: length = 17, Value must match regular expression
^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:4D:45:45:4D
The target of this virtual network interface.
If absent, this virtual network interface is not attached to a target.
The URL for this share mount target
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/shares/0fe9e5d8-0a4d-4818-96ec-e99708644a58/mount_targets/4cf9171a-0043-4434-8727-15b53dbc374c
The unique identifier for this share mount target
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
4cf9171a-0043-4434-8727-15b53dbc374c
The name for this share mount target. The name is unique across all mount targets for the file share.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-share-mount-target
The resource type
Possible values: [
share_mount_target
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Status Code
The virtual network interface was updated successfully.
An invalid virtual network interface patch was provided.
The specified virtual network interface is owned by the provider.
A virtual network interface with the specified identifier could not be found.
The virtual network interface's
allow_ip_spoofing
property cannot betrue
whentarget
specifies a share mount target.
{ "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2019-01-31T03:42:32.993Z", "crn": "crn:[...]", "enable_infrastructure_nat": false, "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef", "ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6A", "name": "my-network-interface-updated", "primary_ip": { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/a929f12d-fb45-4e5e-9864-95e171ae3589", "id": "a929f12d-fb45-4e5e-9864-95e171ae3589", "name": "my-security-group" } ], "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/9270d819-c05e-4352-99e4-80c4680cdb7c", "id": "9270d819-c05e-4352-99e4-80c4680cdb7c", "name": "my-subnet", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all floating IPs associated with a virtual network interface
This request lists all floating IPs associated with a virtual network interface.
GET /virtual_network_interfaces/{virtual_network_interface_id}/floating_ips
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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-name
sorts the collection by thename
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
address
,name
]Default:
address
Example:
name
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/floating_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listNetworkInterfaceFloatingIpsOptions := &vpcv1.ListNetworkInterfaceFloatingIpsOptions{ VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } floatingIpCollection, response, err := vpcService.ListNetworkInterfaceFloatingIps(listNetworkInterfaceFloatingIpsOptions)
ListNetworkInterfaceFloatingIpsOptions listNetworkInterfaceFloatingIpsOptions = new ListNetworkInterfaceFloatingIpsOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .build(); Response<FloatingIPCollectionVirtualNetworkInterfaceContext> response = vpcService.listNetworkInterfaceFloatingIps(listNetworkInterfaceFloatingIpsOptions).execute(); FloatingIPCollectionVirtualNetworkInterfaceContext floatingIpCollection = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, }; const response = await vpcService.listNetworkInterfaceFloatingIps(params);
response = vpc_service.list_network_interface_floating_ips( virtual_network_interface_id=virtualNetworkInterfaceId, ) floating_ip_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9/floating_ips?limit=20
first
Collection of floating IPs bound to the virtual network interface specified by the identifier in the URL
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-fa41aecb-4f21-423d-8082-630bfba1e1d9/floating_ips?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The associated floating IPs were retrieved successfully.
A virtual network interface with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef/floating_ips?limit=50" }, "floating_ips": [ { "address": "192.0.2.2", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "id": "r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip" } ], "limit": 50, "total_count": 1 }
Disassociate a floating IP from a virtual network interface
This request disassociates the specified floating IP from the specified virtual network interface
DELETE /virtual_network_interfaces/{virtual_network_interface_id}/floating_ips/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
removeNetworkInterfaceFloatingIPOptions := &vpcv1.RemoveNetworkInterfaceFloatingIPOptions{ ID: &floatingIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } response, err := vpcService.RemoveNetworkInterfaceFloatingIP(getNetworkInterfaceFloatingIPOptions)
RemoveNetworkInterfaceFloatingIpOptions removeNetworkInterfaceFloatingIpOptions = new RemoveNetworkInterfaceFloatingIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(floatingIpId) .build(); Response<Void> response = vpcService.removeNetworkInterfaceFloatingIp(removeNetworkInterfaceFloatingIpOptions).execute();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: floatingIpId, }; const response = await vpcService.removeNetworkInterfaceFloatingIp(params);
response = vpc_service.remove_network_interface_floating_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=floatingIpId, )
Retrieve associated floating IP
This request retrieves a specified floating IP if it is associated with the virtual network interface specified in the URL
GET /virtual_network_interfaces/{virtual_network_interface_id}/floating_ips/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getNetworkInterfaceFloatingIPOptions := &vpcv1.GetNetworkInterfaceFloatingIPOptions{ ID: &floatingIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } floatingIp, response, err := vpcService.GetNetworkInterfaceFloatingIP(getNetworkInterfaceFloatingIPOptions)
GetNetworkInterfaceFloatingIpOptions getNetworkInterfaceFloatingIpOptions = new GetNetworkInterfaceFloatingIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(floatingIpId) .build(); Response<FloatingIPReference> response = vpcService.getNetworkInterfaceFloatingIp(getNetworkInterfaceFloatingIpOptions).execute(); FloatingIPReference floatingIp = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: floatingIpId, }; const response = await vpcService.getNetworkInterfaceFloatingIp(params);
response = vpc_service.get_network_interface_floating_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=floatingIpId, ) floating_ip = response.get_result()
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The associated floating IP was retrieved successfully.
The floating IP is not associated with a virtual network interface with the specified identifier
{ "address": "192.0.2.2", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "id": "r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip" }
Add an association between a floating IP and a virtual network interface
This request adds an association between the specified floating IP and the specified virtual network interface.
If the virtual network interface has enable_infrastructure_nat
set to true
, no more
than one floating IP can be associated, and network address translation is performed
between the floating IP address and the virtual network interface's primary_ip
address.
If the virtual network interface has enable_infrastructure_nat
set to false
, packets
are passed unchanged to/from the virtual network interface.
The floating IP must:
- be in the same
zone
as the virtual network interface - not currently be associated with another resource
The virtual network interface's target
must not currently be a file share mount
target.
A request body is not required, and if provided, is ignored.
PUT /virtual_network_interfaces/{virtual_network_interface_id}/floating_ips/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.virtual-network-interface.virtual-network-interface.attach
is.floating-ip.floating-ip.attach
is.virtual-network-interface.virtual-network-interface.detach
Generated when a floating IP that was attached to a virtual network interface is replaced
is.instance.network-interface.detach
Generated when a floating IP that was attached to an instance network interface is replaced
is.bare-metal-server.network-interface.detach
Generated when a floating IP that was attached to a bare metal server network interface is replaced
is.floating-ip.floating-ip.detach
Generated when a floating IP that was attached to a resource is replaced
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
addNetworkInterfaceFloatingIPOptions := &vpcv1.AddNetworkInterfaceFloatingIPOptions{ ID: &floatingIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } floatingIp, response, err := vpcService.AddNetworkInterfaceFloatingIP(getNetworkInterfaceFloatingIPOptions)
AddNetworkInterfaceFloatingIpOptions addNetworkInterfaceFloatingIpOptions = new AddNetworkInterfaceFloatingIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(floatingIpId) .build(); Response<FloatingIPReference> response = vpcService.addNetworkInterfaceFloatingIp(addNetworkInterfaceFloatingIpOptions).execute(); FloatingIPReference floatingIp = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: floatingIpId, }; const response = await vpcService.addNetworkInterfaceFloatingIp(params);
response = vpc_service.add_network_interface_floating_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=floatingIpId, ) floating_ip_reference = response.get_result()
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The specified floating IP is already associated with the virtual network interface.
The floating IP was successfully associated with the virtual network interface.
The specified floating IP could not be associated with the specified virtual network interface.
The specified virtual network interface or floating IP could not be found.
The request specified one or more of:
- a floating IP associated with another resource
- a virtual network interface that has
enable_infrastructure_nat
set totrue
and another floating IP associated with it - a virtual network interface whose
target
is a file share mount target
{ "address": "192.0.2.2", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "id": "r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip" }
{ "address": "192.0.2.2", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "id": "r006-ac0deed3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip" }
List all reserved IPs bound to a virtual network interface
This request lists all reserved IPs bound to a virtual network interface.
GET /virtual_network_interfaces/{virtual_network_interface_id}/ips
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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-name
sorts the collection by thename
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
address
,name
]Default:
address
Example:
name
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVirtualNetworkInterfaceIpsOptions := &vpcv1.ListVirtualNetworkInterfaceIpsOptions{ VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } reservedIpCollection, response, err := vpcService.ListVirtualNetworkInterfaceIps(listVirtualNetworkInterfaceIpsOptions)
ListVirtualNetworkInterfaceIpsOptions listVirtualNetworkInterfaceIpsOptions = new ListVirtualNetworkInterfaceIpsOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .build(); Response<ReservedIPCollectionVirtualNetworkInterfaceContext> response = vpcService.listVirtualNetworkInterfaceIps(listVirtualNetworkInterfaceIpsOptions).execute(); ReservedIPCollectionVirtualNetworkInterfaceContext reservedIpCollection = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, }; const response = await vpcService.listVirtualNetworkInterfaceIps(params);
response = vpc_service.list_virtual_network_interface_ips( virtual_network_interface_id=virtualNetworkInterfaceId, ) reserved_ip_collection = response.get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?limit=20
first
Collection of reserved IPs bound to the virtual network interface specified by the identifier in the URL
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/10c02d81-0ecb-4dc5-897d-28392913b81e/ips?start=a404e343444b4e1095c9edba76672d67&limit=20
next
Status Code
The reserved IPs were retrieved successfully.
A virtual network interface with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-54eb57ee-86f2-4796-90bb-d7874e0831ef/ips?limit=20" }, "ips": [ { "address": "10.240.0.6", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "limit": 20, "total_count": 1 }
Unbind a reserved IP from a virtual network interface
This request unbinds the specified reserved IP from the specified virtual network
interface. If the reserved IP has auto_delete
set to true
, the reserved IP will be
deleted.
The reserved IP for the primary_ip
cannot be unbound.
DELETE /virtual_network_interfaces/{virtual_network_interface_id}/ips/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
removeVirtualNetworkInterfaceIPOptions := &vpcv1.RemoveVirtualNetworkInterfaceIPOptions{ ID: &reservedIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } response, err := vpcService.RemoveVirtualNetworkInterfaceIP(removeVirtualNetworkInterfaceIPOptions)
RemoveVirtualNetworkInterfaceIpOptions removeVirtualNetworkInterfaceIpOptions = new RemoveVirtualNetworkInterfaceIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(reservedIpId) .build(); Response<Void> response = vpcService.removeVirtualNetworkInterfaceIp(removeVirtualNetworkInterfaceIpOptions).execute();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: reservedIpId, }; const response = await vpcService.removeVirtualNetworkInterfaceIp(params);
response = vpc_service.remove_virtual_network_interface_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=reservedIpId, )
Retrieve bound reserved IP
This request retrieves the specified reserved IP address if it is bound to the virtual network interface specified in the URL.
GET /virtual_network_interfaces/{virtual_network_interface_id}/ips/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVirtualNetworkInterfaceIPOptions := &vpcv1.getVirtualNetworkInterfaceIPOptions{ ID: &reservedIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } reservedIp, response, err := vpcService.GetVirtualNetworkInterfaceIP(getVirtualNetworkInterfaceIPOptions)
GetVirtualNetworkInterfaceIpOptions getVirtualNetworkInterfaceIpOptions = new GetVirtualNetworkInterfaceIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(reservedIpId) .build(); Response<ReservedIPReference> response = vpcService.getVirtualNetworkInterfaceIp(getVirtualNetworkInterfaceIpOptions).execute(); ReservedIPReference reservedIp = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: reservedIpId, }; const response = await vpcService.getVirtualNetworkInterfaceIp(params);
response = vpc_service.get_virtual_network_interface_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=reservedIpId, ) reserved_ip_reference = response.get_result()
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The associated reserved IP was retrieved successfully.
The reserved IP address with the specified identifier could not be found
{ "address": "10.240.0.6", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }
Bind a reserved IP to a virtual network interface
This request binds the specified reserved IP to the specified virtual network interface.
The reserved IP must currently be unbound and in the primary IP's subnet.
The virtual network interface's target
must not currently be a file share mount target.
PUT /virtual_network_interfaces/{virtual_network_interface_id}/ips/{id}
Request
Path Parameters
The virtual network interface identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
addVirtualNetworkInterfaceIPOptions := &vpcv1.AddVirtualNetworkInterfaceIPOptions{ ID: &reservedIpId, VirtualNetworkInterfaceID: &virtualNetworkInterfaceId, } reservedIp, response, err := vpcService.AddVirtualNetworkInterfaceIP(addVirtualNetworkInterfaceIPOptions)
AddVirtualNetworkInterfaceIpOptions addVirtualNetworkInterfaceIpOptions = new AddVirtualNetworkInterfaceIpOptions.Builder() .virtualNetworkInterfaceId(virtualNetworkInterfaceId) .id(reservedIpId) .build(); Response<ReservedIPReference> response = vpcService.addVirtualNetworkInterfaceIp(addVirtualNetworkInterfaceIpOptions).execute(); ReservedIPReference reservedIpReference = response.getResult();
const params = { virtualNetworkInterfaceId: virtualNetworkInterfaceId, id: reservedIpId, }; const response = await vpcService.addVirtualNetworkInterfaceIp(params);
response = vpc_service.add_virtual_network_interface_ip( virtual_network_interface_id=virtualNetworkInterfaceId, id=reservedIpId, ) reserved_ip_reference = response.get_result()
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The specified reserved IP is already bound to the virtual network interface.
The reserved IP was successfully bound to the virtual network interface.
The specified reserved IP is not in the primary IP's subnet.
A virtual network interface with the specified identifier could not be found.
The request specified one or more of:
- a bound reserved IP
- a virtual network interface for a file share mount target and a reserved IP that is not the primary IP address
{ "address": "10.240.0.6", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }
{ "address": "10.240.0.6", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }
List all public gateways
This request lists all public gateways in the region. A public gateway is a virtual network device associated with a VPC, which allows access to the Internet. A public gateway resides in a zone and can be connected to subnets in the same zone only.
GET /public_gateways
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
curl -X GET "$vpc_api_endpoint/v1/public_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListPublicGatewaysOptions{} publicGateways, response, err := vpcService.ListPublicGateways(options)
ListPublicGatewaysOptions listPublicGatewaysOptions = new ListPublicGatewaysOptions.Builder() .build(); Response<PublicGatewayCollection> response = service.listPublicGateways(listPublicGatewaysOptions).execute(); PublicGatewayCollection publicGatewayCollection = response.getResult();
const response = await vpcService.listPublicGateways();
response = service.list_public_gateways()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of public gateways
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The public gateways were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways?limit=50" }, "limit": 50, "public_gateways": [ { "created_at": "2019-01-27T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/ba1b3bf9-27ab-498d-8aac-c30b09b5555b", "id": "f94a91c7-95db-42f2-9949-93a7e8fb63fb", "name": "my-public-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }, { "created_at": "2019-01-28T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/e2928e82-e23f-4f31-92b3-5c154e58da09", "id": "ec132615-75a5-417b-a720-dec1d27b22ff", "name": "my-public-gateway-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "total_count": 2 }
Create a public gateway
This request creates a new public gateway from a public gateway prototype object. For this to succeed, the VPC must not already have a public gateway in the specified zone.
If a floating IP is provided, it must be unbound. If a floating IP is not provided, one will be created and bound to the public gateway. Once a public gateway has been created, its floating IP cannot be unbound. A public gateway must be explicitly attached to each subnet it will provide connectivity for.
POST /public_gateways
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The public gateway prototype object
The VPC this public gateway will reside in
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The zone this public gateway will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The name for this public gateway. The name must not be used by another public gateway in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-public-gateway
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/public_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-public-gateway", "vpc": { "id":"a0819609-0997-4f92-9409-86c95ddf59d3" }, "zone": { "name": "us-south-1" } }'
options := &vpcv1.CreatePublicGatewayOptions{} options.SetVpc(&vpcv1.VPCIdentity{ ID: &vpcID, }) options.SetZone(&vpcv1.ZoneIdentity{ Name: &zoneName, }) publicGateway, response, err := vpcService.CreatePublicGateway(options)
VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcID) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); CreatePublicGatewayOptions createPublicGatewayOptions = new CreatePublicGatewayOptions.Builder() .vpc(vpcIdentityModel) .zone(zoneIdentityModel) .name("my-public-gateway") .build(); Response<PublicGateway> response = service.createPublicGateway(createPublicGatewayOptions).execute(); PublicGateway publicGateway = response.getResult();
const params = { vpc: { id: vpcID }, zone: { name: zoneName }, }; const response = await vpcService.createPublicGateway(params);
vpc_identity_model = {} vpc_identity_model['id'] = vpc_id zone_identity_model = {} zone_identity_model['name'] = zone_name public_gateway_prototype_floating_ip_model = {} public_gateway_prototype_floating_ip_model['id'] = floating_ip_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id vpc = vpc_identity_model zone = zone_identity_model floating_ip = public_gateway_prototype_floating_ip_model name = 'my-public_gateway' resource_group = resource_group_identity_model response = service.create_public_gateway( vpc, zone, floating_ip=floating_ip, name=name, resource_group=resource_group, )
Response
The date and time that the public gateway was created
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The floating IP bound to this public gateway.
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
floating_ip
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource group for this public gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this public gateway
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The VPC this public gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this public gateway resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The public gateway was created successfully.
An invalid public gateway prototype object was provided.
{ "created_at": "2019-01-28T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/d4d3ef82-bebb-446e-bbe4-038bc82f6776", "id": "4fd00a61-fe63-4186-81c9-f7253b5c1cd7", "name": "my-public-gateway", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a public gateway
This request deletes a public gateway. This operation cannot be reversed. For this request to succeed, the public gateway must not be attached to any subnets. The public gateway's floating IP will be automatically unbound. If the floating IP was created when the public gateway was created, it will be deleted.
DELETE /public_gateways/{id}
Request
Path Parameters
The public gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/public_gateways/$public_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeletePublicGatewayOptions{} options.SetID(id) response, err := vpcService.DeletePublicGateway(options)
DeletePublicGatewayOptions deletePublicGatewayOptions = new DeletePublicGatewayOptions.Builder() .id(id) .build(); Response<Void> response = service.deletePublicGateway(deletePublicGatewayOptions).execute();
const response = await vpcService.deletePublicGateway({ id });
response = service.delete_public_gateway(id)
Retrieve a public gateway
This request retrieves a single public gateway specified by the identifier in the URL.
GET /public_gateways/{id}
Request
Path Parameters
The public gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/public_gateways/$public_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetPublicGatewayOptions{} options.SetID(id) publicGateway, response, err := vpcService.GetPublicGateway(options)
GetPublicGatewayOptions getPublicGatewayOptions = new GetPublicGatewayOptions.Builder() .id(id) .build(); Response<PublicGateway> response = service.getPublicGateway(getPublicGatewayOptions).execute(); PublicGateway publicGateway = response.getResult();
const response = await vpcService.getPublicGateway({ id });
response = service.get_public_gateway(id)
Response
The date and time that the public gateway was created
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The floating IP bound to this public gateway.
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
floating_ip
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource group for this public gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this public gateway
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The VPC this public gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this public gateway resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The public gateway was retrieved successfully.
A public gateway with the specified identifier could not be found.
{ "created_at": "2019-01-27T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/d4d3ef82-bebb-446e-bbe4-038bc82f6776", "id": "ba1b3bf9-27ab-498d-8aac-c30b09b5555b", "name": "my-public-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Request
Path Parameters
The public gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The public gateway patch
The name for this public gateway. The name must not be used by another public gateway in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-public-gateway
curl -X PATCH "$vpc_api_endpoint/v1/public_gateways/$public_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-public-gateway" }'
options := &vpcv1.UpdatePublicGatewayOptions{} options.SetID(id) options.SetName(name) publicGateway, response, err := vpcService.UpdatePublicGateway(options)
UpdatePublicGatewayOptions updatePublicGatewayOptions = new UpdatePublicGatewayOptions.Builder() .id(id) .name(name) .build(); Response<PublicGateway> response = service.updatePublicGateway(updatePublicGatewayOptions).execute(); PublicGateway publicGateway = response.getResult();
const response = await vpcService.updatePublicGateway({ id, name: 'my-public-gateway', });
response = service.update_public_gateway( id, name='my-public-gateway', )
Response
The date and time that the public gateway was created
The CRN for this public gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::public-gateway:dc5431ef-1fc6-4861-adc9-a59d077d1241
The floating IP bound to this public gateway.
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
floating_ip
The URL for this public gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/public_gateways/dc5431ef-1fc6-4861-adc9-a59d077d1241
The unique identifier for this public gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dc5431ef-1fc6-4861-adc9-a59d077d1241
The name for this public gateway. The name is unique across all public gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-public-gateway
The resource group for this public gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
public_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of this public gateway
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The VPC this public gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The zone this public gateway resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
Status Code
The public gateway was updated successfully.
An invalid public gateway patch was provided.
A public gateway with the specified identifier could not be found.
{ "created_at": "2019-01-27T06:47:20Z", "crn": "crn:[...]", "floating_ip": { "address": "192.0.2.2", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "f5380e82-cba3-4efa-b17c-ef0993936e05", "name": "my-floating-ip-1" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/public_gateways/d4d3ef82-bebb-446e-bbe4-038bc82f6776", "id": "d4d3ef82-bebb-446e-bbe4-038bc82f6776", "name": "my-public-gateway", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "public_gateway", "status": "available", "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc-1", "resource_type": "vpc" }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all floating IPs
This request lists all floating IPs in the region. Floating IPs allow inbound and outbound traffic from the Internet to an instance.
GET /floating_ips
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to resources with a
target.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
target.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Filters the collection to resources with a
target.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-resource
Filters the collection to resources with a
target.resource_type
property matching the specified value.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/floating_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listFloatingIpsOptions := vpcService.NewListFloatingIpsOptions() floatingIPs, response, err := vpcService.ListFloatingIps(listFloatingIpsOptions)
ListFloatingIpsOptions listFloatingIpsOptions = new ListFloatingIpsOptions.Builder() .limit(Long.valueOf("10")) .build(); Response<FloatingIPCollection> response = service.listFloatingIps(listFloatingIpsOptions).execute(); FloatingIPCollection floatingIpCollectionResult = response.getResult();
const response = await vpcService.listFloatingIps();
response = service.list_floating_ips()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips?limit=20
first
Collection of floating IPs
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The floating IPs were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips?limit=50" }, "floating_ips": [ { "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "available", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "id": "0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "virtual_network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }, { "address": "198.51.100.1", "created_at": "2019-01-29T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/64580c28-713a-4cda-9993-53bc6a529bb4", "id": "64580c28-713a-4cda-9993-53bc6a529bb4", "name": "my-floating-ip-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "available", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-48ec0633-2cd2-4314-ab31-8744a1a6a16b", "id": "0767-48ec0633-2cd2-4314-ab31-8744a1a6a16b", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.10", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5/reserved_ips/c6f1e6b0-ba99-4a9a-b8de-82d4ed507272", "id": "c6f1e6b0-ba99-4a9a-b8de-82d4ed507272", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "resource_type": "virtual_network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } } ], "limit": 50, "total_count": 2 }
Reserve a floating IP
This request reserves a new floating IP.
POST /floating_ips
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.floating-ip.floating-ip.create
is.floating-ip.floating-ip.attach
Generated when
target
is specifiedis.instance.network-interface.attach
Generated when
target
specifies an instance network interfaceis.bare-metal-server.network-interface.attach
Generated when
target
specifies a bare metal server network interfaceis.virtual-network-interface.virtual-network-interface.attach
Generated when
target
specifies a virtual network interface
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The floating IP prototype object
The name for this floating IP. The name must not be used by another floating IP in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-floating-ip
The resource group to use. If unspecified, the account's default resource group will be used.
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
resource_group
The zone this floating IP will reside in
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
One of
curl -X POST "$vpc_api_endpoint/v1/floating_ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-floating-ip-1", "target": { "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847" } }'
options := &vpcv1.CreateFloatingIPOptions{} options.SetFloatingIPPrototype(&vpcv1.FloatingIPPrototype{ Name: &name, Zone: &vpcv1.ZoneIdentity{ Name: &zone, }, }) floatingIP, response, err := vpcService.CreateFloatingIP(options)
ResourceGroupIdentityById resourceGroupIdentityModel = new ResourceGroupIdentityById.Builder() .id(resourceGroupId) .build(); ZoneIdentityByName zoneIdentityModel = new ZoneIdentityByName.Builder() .name(zoneName) .build(); FloatingIPPrototypeFloatingIPByZone floatingIpPrototypeModel = new FloatingIPPrototypeFloatingIPByZone.Builder() .name("my-floating-ip") .resourceGroup(resourceGroupIdentityModel) .zone(zoneIdentityModel) .build(); CreateFloatingIpOptions createFloatingIpOptions = new CreateFloatingIpOptions.Builder() .floatingIpPrototype(floatingIpPrototypeModel) .build(); Response<FloatingIP> response = service.createFloatingIp(createFloatingIpOptions).execute(); FloatingIP floatingIpResult = response.getResult();
const params = { floatingIpPrototype: { name: 'my-floating-ip', zone: zoneName, }, }; const response = await vpcService.createFloatingIp(params);
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id zone_identity_model = {} zone_identity_model['name'] = zoneName floating_ip_prototype_model = {} floating_ip_prototype_model['name'] = my-floating_ip floating_ip_prototype_model[ 'resource_group'] = resource_group_identity_model floating_ip_prototype_model['zone'] = zone_identity_model floating_ip_prototype = floating_ip_prototype_model response = service.create_floating_ip(floating_ip_prototype)
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The floating IP was reserved successfully.
An invalid floating IP prototype object was provided.
The specified target already has a floating IP bound to it.
{ "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "pending", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "id": "0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "virtual_network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Delete a floating IP
This request disassociates (if associated) and releases a floating IP. This operation cannot be reversed. For this request to succeed, the floating IP must not be required by another resource, such as a public gateway.
DELETE /floating_ips/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.floating-ip.floating-ip.delete
is.floating-ip.floating-ip.detach
Generated for a floating IP that was attached
is.bare-metal-server.network-interface.detach
Generated for a floating IP that was attached to a bare metal server network interface
is.instance.network-interface.detach
Generated for a floating IP that was attached to an instance network interface
is.virtual-network-interface.virtual-network-interface.detach
Generated for a floating IP that was attached to a virtual network interface
Request
Path Parameters
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteFloatingIPOptions(id) response, err = vpcService.DeleteFloatingIP(options)
DeleteFloatingIpOptions deleteFloatingIpOptions = new DeleteFloatingIpOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteFloatingIp(deleteFloatingIpOptions).execute();
const response = await vpcService.deleteFloatingIp({ id });
response = service.delete_floating_ip(id)
Retrieve a floating IP
This request retrieves a single floating IP specified by the identifier in the URL.
GET /floating_ips/{id}
Request
Path Parameters
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetFloatingIPOptions(id) floatingIP, response, err = vpcService.GetFloatingIP(options)
GetFloatingIpOptions getFloatingIpOptions = new GetFloatingIpOptions.Builder() .id(id) .build(); Response<FloatingIP> response = service.getFloatingIp(getFloatingIpOptions).execute(); FloatingIP floatingIpResult = response.getResult();
const response = await vpcService.getFloatingIp({ id });
response = service.get_floating_ip(id)
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The floating IP was retrieved successfully.
The specified floating IP could not be found.
{ "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "available", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "id": "0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "virtual_network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
Update a floating IP
This request updates a floating IP's name and/or target.
PATCH /floating_ips/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.floating-ip.floating-ip.update
is.floating-ip.floating-ip.attach
Generated when
target
is specifiedis.floating-ip.floating-ip.detach
Generated when an existing target is replaced
is.bare-metal-server.network-interface.attach
Generated when
target
specifies a bare metal server network interfaceis.bare-metal-server.network-interface.detach
Generated when an existing bare metal server network interface target is replaced
is.instance.network-interface.attach
Generated when
target
specifies an instance network interfaceis.instance.network-interface.detach
Generated when an existing instance network interface target is replaced
is.virtual-network-interface.virtual-network-interface.attach
Generated when
target
specifies a virtual network interfaceis.virtual-network-interface.virtual-network-interface.detach
Generated when an existing virtual network interface target is replaced
Request
Path Parameters
The floating IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The floating IP patch
The name for this floating IP. The name must not be used by another floating IP in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-floating-ip
The target resource to bind this floating IP to, replacing any existing binding. The floating IP must not be required by another resource, such as a public gateway.
The target resource must not already have a floating IP bound to it if the target resource is:
- an instance network interface
- a bare metal server network interface with
enable_infrastructure_nat
set totrue
- a virtual network interface with
enable_infrastructure_nat
set totrue
Specify
null
to remove an existing binding.
curl -X PATCH "$vpc_api_endpoint/v1/floating_ips/$floating_ip_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-floating-ip-1" }'
options := &vpcv1.UpdateFloatingIPOptions{ ID: &id, Name: &name, } options.SetTarget(&vpcv1.NetworkInterfaceIdentity{ ID: &targetId, }) floatingIPs, response, err := vpcService.UpdateFloatingIP(options)
FloatingIPPatchTargetNetworkInterfaceIdentityNetworkInterfaceIdentityById floatingIpPatchTargetNetworkInterfaceIdentityModel = new FloatingIPPatchTargetNetworkInterfaceIdentityNetworkInterfaceIdentityById.Builder() .id(targetId) .build(); UpdateFloatingIpOptions updateFloatingIpOptions = new UpdateFloatingIpOptions.Builder() .id(id) .name("my-floating-ip") .target(floatingIpPatchTargetNetworkInterfaceIdentityModel) .build(); Response<FloatingIP> response = service.updateFloatingIp(updateFloatingIpOptions).execute(); FloatingIP floatingIpResult = response.getResult();
const response = await vpcService.updateFloatingIp({ id, name: 'my-floating-ip', });
network_interface_identity_model = {} network_interface_identity_model['id'] = network_interface_id target = network_interface_identity_model name = 'my-floating_ip' response = service.update_floating_ip( id, name=name, target=target, )
Response
The globally unique IP address
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
203.0.113.1
The date and time that the floating IP was created
The CRN for this floating IP
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this floating IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/floating_ips/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this floating IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The name for this floating IP. The name is unique across all floating IPs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-floating-ip
The resource group for this floating IP
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The status of the floating IP
Possible values: [
available
,deleting
,failed
,pending
]Example:
available
The zone this floating IP resides in
Examples:ViewThe URL for this zone
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
zone
The target of this floating IP
Status Code
The floating IP was updated successfully.
An invalid floating IP patch was provided.
A floating IP with the specified identifier could not be found.
The floating IP is required by another resource, or the specified target already has a floating IP bound to it.
{ "address": "192.0.2.2", "created_at": "2019-01-28T12:08:05Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "name": "my-floating-ip-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "status": "available", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/virtual_network_interfaces/0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "id": "0767-4f2da0d1-85ce-40a3-a846-9bfc6222c469", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.9", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/7ec86020-1c6e-4889-b3f0-a15f2e50f87e/reserved_ips/6d353a0f-aeb1-4ae1-832e-1110d10981bb", "id": "6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "resource_type": "virtual_network_interface", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5", "name": "my-subnet-1", "resource_type": "subnet" } }, "zone": { "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1", "name": "us-south-1" } }
List all network ACLs
This request lists all network ACLs in the region. A network ACL defines a set of packet filtering (5-tuple) rules for all traffic in and out of a subnet. Both allow and deny rules can be defined, and rules are stateless such that reverse traffic in response to allowed traffic is not automatically permitted.
GET /network_acls
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
curl -X GET "$vpc_api_endpoint/v1/network_acls?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListNetworkAclsOptions{} acls, response, err := vpcService.ListNetworkAcls(options)
ListNetworkAclsOptions listNetworkAclsOptions = new ListNetworkAclsOptions.Builder() .build(); Response<NetworkACLCollection> response = service.listNetworkAcls(listNetworkAclsOptions).execute(); NetworkACLCollection networkAclCollection = response.getResult();
const response = await vpcService.listNetworkAcls();
response = service.list_network_acls()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of network ACLs
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The network ACLs were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls?limit=50" }, "limit": 50, "network_acls": [ { "created_at": "2019-01-29T06:26:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/e9d38838-7531-4383-bd01-662e10527f29", "id": "e9d38838-7531-4383-bd01-662e10527f29", "name": "my-network-acl-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }, { "created_at": "2019-01-29T07:21:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/a2ce7c07-7775-4aa6-b0c4-320ad5340f84", "id": "a2ce7c07-7775-4aa6-b0c4-320ad5340f84", "name": "my-network-acl-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } } ], "total_count": 2 }
Create a network ACL
This request creates a new stateless network ACL from a network ACL prototype object. The prototype object is structured in the same way as a retrieved network ACL, and contains the information necessary to create the new network ACL.
POST /network_acls
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The network ACL prototype object
The VPC this network ACL will reside in
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The name for this network ACL. The name must not be used by another network ACL for the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-network-acl
The resource group to use. If unspecified, the account's default resource group will be used.
The prototype objects for rules to create along with this network ACL. If unspecified, no rules will be created, resulting in all traffic being denied.
One of
curl -X POST "$vpc_api_endpoint/v1/network_acls?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-network-acl", "vpc": { "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f" } }'
options := &vpcv1.CreateNetworkACLOptions{} options.SetNetworkACLPrototype(&vpcv1.NetworkACLPrototype{ Name: &name, SourceNetworkAcl: &vpcv1.NetworkACLIdentity{ ID: ©ableAclID, }, Vpc: &vpcv1.VPCIdentity{ ID: &vpcID, }, }) acl, response, err := vpcService.CreateNetworkACL(options)
VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); NetworkACLPrototypeNetworkACLByRules networkAclPrototypeModel = new NetworkACLPrototypeNetworkACLByRules.Builder() .name("my-network-acl") .vpc(vpcIdentityModel) .build(); CreateNetworkAclOptions createNetworkAclOptions = new CreateNetworkAclOptions.Builder() .networkAclPrototype(networkAclPrototypeModel) .build(); Response<NetworkACL> response = service.createNetworkAcl(createNetworkAclOptions).execute(); NetworkACL networkAcl = response.getResult();
const networkAclRulePrototypeNetworkAclContextModel = { name: 'my-network-acl-rule', action: 'allow', destination: '192.168.3.2/32', direction: 'inbound', source: '192.168.3.2/32', protocol: 'tcp', }; const networkAclPrototypeModel = { name: 'my-network-acl', vpc: { id: vpcID, }, rules: [networkAclRulePrototypeNetworkAclContextModel], }; const params = { networkAclPrototype: networkAclPrototypeModel, }; const response = await vpcService.createNetworkAcl(params);
network_acl_rule_prototype_network_acl_context_model = {} network_acl_rule_prototype_network_acl_context_model['action'] = 'allow' network_acl_rule_prototype_network_acl_context_model[ 'destination'] = '192.168.3.0/24' network_acl_rule_prototype_network_acl_context_model[ 'direction'] = 'inbound' network_acl_rule_prototype_network_acl_context_model[ 'id'] = network_acl_rule_id network_acl_rule_prototype_network_acl_context_model[ 'ip_version'] = 'ipv4' network_acl_rule_prototype_network_acl_context_model[ 'name'] = 'my-rule-2' network_acl_rule_prototype_network_acl_context_model['protocol'] = 'udp' network_acl_rule_prototype_network_acl_context_model[ 'source'] = '192.168.3.0/24' network_acl_rule_prototype_network_acl_context_model[ 'destination_port_max'] = 22 network_acl_rule_prototype_network_acl_context_model[ 'destination_port_min'] = 22 network_acl_rule_prototype_network_acl_context_model[ 'source_port_max'] = 65535 network_acl_rule_prototype_network_acl_context_model[ 'source_port_min'] = 49152 resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id vpc_identity_model = {} vpc_identity_model['id'] = vpc_id network_acl_prototype_model = {} network_acl_prototype_model['name'] = 'my-network-acl' network_acl_prototype_model[ 'resource_group'] = resource_group_identity_model network_acl_prototype_model['vpc'] = vpc_identity_model network_acl_prototype_model['rules'] = [ network_acl_rule_prototype_network_acl_context_model ] network_acl_reference_model = {} network_acl_reference_model['id'] = source_network_acl_id network_acl_prototype_model['source_network_acl'] = network_acl_reference_model network_acl_prototype = network_acl_prototype_model response = service.create_network_acl( network_acl_prototype=network_acl_prototype)
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
The resource group for this network ACL
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for this network ACL. If no rules exist, all traffic will be denied.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The network ACL was created successfully
An invalid network ACL prototype object was provided.
{ "created_at": "2019-01-29T06:26:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [], "subnets": [ { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:8722d01c-9c78-4555-82b5-53ad1266f959", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
Delete a network ACL
This request deletes a network ACL. This operation cannot be reversed. For this request to succeed, the network ACL must not be the default network ACL for any VPCs, and the network ACL must not be attached to any subnets.
DELETE /network_acls/{id}
Request
Path Parameters
The network ACL identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/network_acls/$network_acl_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteNetworkACLOptions{} options.SetID(ID) response, err := vpcService.DeleteNetworkACL(options)
DeleteNetworkAclRuleOptions deleteNetworkAclRuleOptions = new DeleteNetworkAclRuleOptions.Builder() .networkAclId(networkAclId) .id(id) .build(); Response<Void> response = service.deleteNetworkAclRule(deleteNetworkAclRuleOptions).execute();
const response = await vpcService.deleteNetworkAcl({ id });
response = service.delete_network_acl(id)
Retrieve a network ACL
This request retrieves a single network ACL specified by the identifier in the URL.
GET /network_acls/{id}
Request
Path Parameters
The network ACL identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/network_acls/$network_acl_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetNetworkACLOptions{} options.SetID(ID) acl, response, err := vpcService.GetNetworkACL(options)
GetNetworkAclOptions getNetworkAclOptions = new GetNetworkAclOptions.Builder() .id(id) .build(); Response<NetworkACL> response = service.getNetworkAcl(getNetworkAclOptions).execute(); NetworkACL networkAcl = response.getResult();
const response = await vpcService.getNetworkAcl({ id });
response = service.get_network_acl(id)
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
The resource group for this network ACL
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for this network ACL. If no rules exist, all traffic will be denied.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The network ACL was retrieved successfully
A network ACL with the specified identifier could not be found.
{ "created_at": "2019-01-29T07:21:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/e9d38838-7531-4383-bd01-662e10527f29", "id": "e9d38838-7531-4383-bd01-662e10527f29", "name": "my-network-acl-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T07:21:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
Request
Path Parameters
The network ACL identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The network ACL patch
The name for this network ACL. The name must not be used by another network ACL for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-network-acl
curl -X PATCH "$vpc_api_endpoint/v1/network_acls/$network_acl_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-network-acl-updated" }'
options := &vpcv1.UpdateNetworkACLOptions{} options.SetID(id) options.SetName(name) acl, response, err := vpcService.UpdateNetworkACL(options)
UpdateNetworkAclOptions updateNetworkAclOptions = new UpdateNetworkAclOptions.Builder() .id(id) .name(name) .build(); Response<NetworkACL> response = service.updateNetworkAcl(updateNetworkAclOptions).execute(); NetworkACL networkAcl = response.getResult();
const response = await vpcService.updateNetworkAcl({ id, name: 'my-network-acl', });
response = service.update_network_acl( id, name=name, )
Response
The date and time that the network ACL was created
The CRN for this network ACL
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::network-acl:r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The URL for this network ACL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The unique identifier for this network ACL
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-a4e28308-8ee7-46ab-8108-9f881f22bdbf
The name for this network ACL. The name is unique across all network ACLs for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-network-acl
The resource group for this network ACL
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The ordered rules for this network ACL. If no rules exist, all traffic will be denied.
rules
The subnets to which this network ACL is attached
The VPC this network ACL resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The network ACL was updated successfully.
An invalid network ACL patch was provided.
A network ACL with the specified identifier could not be found.
{ "created_at": "2019-02-02T02:26:17Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d", "id": "3217cb8b-5368-452a-9399-a84f14fb539d", "name": "my-network-acl-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "my-allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "my-allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/f0aae929-7047-46d1-92e1-9102b07a7f6f", "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f", "name": "my-vpc", "resource_type": "vpc" } }
List all rules for a network ACL
This request lists all rules for a network ACL. These rules can allow or deny traffic between a source CIDR block and a destination CIDR block over a particular protocol and port range.
GET /network_acls/{network_acl_id}/rules
Request
Path Parameters
The network ACL identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to rules with a
direction
property matching the specified value.Allowable values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListNetworkACLRulesOptions{} options.SetNetworkACLID(aclID) rules, response, err := vpcService.ListNetworkACLRules(options)
ListNetworkAclRulesOptions listNetworkAclRulesOptions = new ListNetworkAclRulesOptions.Builder() .networkAclId(networkAclId) .build(); Response<NetworkACLRuleCollection> response = service.listNetworkAclRules(listNetworkAclRulesOptions).execute(); NetworkACLRuleCollection networkAclRuleCollection = response.getResult();
const response = await vpcService.listNetworkAclRules({ id: networkAclId });
response = service.list_network_acl_rules(network_acl_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Ordered collection of network ACL rules
rules
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The network ACL rules were retrieved successfully.
A network ACL with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules?limit=50" }, "limit": 50, "rules": [ { "action": "deny", "created_at": "2019-01-07T04:01:28Z", "destination": "0.0.0.0/0", "destination_port_max": 22, "destination_port_min": 22, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "allow-all-inbound-rule", "protocol": "tcp", "source": "0.0.0.0/0", "source_port_max": 65535, "source_port_min": 1 }, { "action": "allow", "created_at": "2019-01-07T04:01:24Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/2c46afc9-b30a-4453-8897-1096383fb053", "id": "2c46afc9-b30a-4453-8897-1096383fb053", "ip_version": "ipv4", "name": "allow-all-outbound-rule", "protocol": "all", "source": "0.0.0.0/0" }, { "action": "allow", "created_at": "2019-01-07T04:01:24Z", "destination": "0.0.0.0/0", "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/0b952e7f-0db6-4cbd-954f-92fbcc3acc39", "id": "0b952e7f-0db6-4cbd-954f-92fbcc3acc39", "ip_version": "ipv4", "name": "allow-all-outbound-rule-2", "protocol": "all", "source": "0.0.0.0/0" } ], "total_count": 3 }
Create a rule for a network ACL
This request creates a new rule from a network ACL rule prototype object. The prototype object is structured in the same way as a retrieved rule, and contains the information necessary to create the new rule.
POST /network_acls/{network_acl_id}/rules
Request
Path Parameters
The network ACL identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The network ACL rule prototype object
The action to perform for a packet matching the rule.
Allowable values: [
allow
,deny
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The destination IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all destination addresses.Possible values: 7 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$
Example:
192.168.3.2/32
The direction of traffic to match.
Allowable values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The protocol to enforce.
Allowable values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The source IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all source addresses.Possible values: 7 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$
Example:
192.168.3.2/32
The rule to insert this rule immediately before.
If unspecified, this rule will be inserted after all existing rules
The IP version for this rule
Allowable values: [
ipv4
]Default:
ipv4
The name for this network ACL rule. The name must not be used by another rule for the network ACL. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-rule-2
The protocol to enforce.
Allowable values: [
tcp
,udp
]The inclusive upper bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Default:
65535
Example:
22
The inclusive lower bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Default:
1
Example:
22
The inclusive upper bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Default:
65335
Example:
65535
The inclusive lower bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Default:
1
Example:
49152
One of
curl -X POST "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "inbound-rule-1", "ip_version": "ipv4", "protocol": "all", "source": "0.0.0.0/0", "destination": "0.0.0.0/0", "direction": "inbound", "action": "allow" }'
options := &vpcv1.CreateNetworkACLRuleOptions{} options.SetNetworkACLID(aclID) options.SetNetworkACLRulePrototype(&vpcv1.NetworkACLRulePrototype{ Action: core.StringPtr("allow"), Direction: core.StringPtr("inbound"), Destination: core.StringPtr("0.0.0.0/0"), Source: core.StringPtr("0.0.0.0/0"), Protocol: core.StringPtr("all"), Name: &name, }) rule, response, err := vpcService.CreateNetworkACLRule(options)
NetworkACLRulePrototypeNetworkACLRuleProtocolICMP networkAclRulePrototypeModel = new NetworkACLRulePrototypeNetworkACLRuleProtocolICMP.Builder() .action("allow") .destination("192.168.3.2/32") .direction("inbound") .source("192.168.3.2/32") .protocol("tcp") .name("my-network-acl-rule") .build(); CreateNetworkAclRuleOptions createNetworkAclRuleOptions = new CreateNetworkAclRuleOptions.Builder() .networkAclId(networkAclId) .networkAclRulePrototype(networkAclRulePrototypeModel) .build(); Response<NetworkACLRule> response = service.createNetworkAclRule(createNetworkAclRuleOptions).execute(); NetworkACLRule networkAclRule = response.getResult();
const networkAclRulePrototypeModel = { name: 'my-network-acl-rule', action: 'allow', destination: '192.168.3.2/32', direction: 'inbound', source: '192.168.3.2/32', protocol: 'tcp', code: 0, type: 8, }; const params = { networkAclId, networkAclRulePrototype: networkAclRulePrototypeModel, }; const response = await vpcService.createNetworkAclRule(params);
network_acl_rule_reference_model = {} network_acl_rule_reference_model[ 'id'] = network_acl_rule_id network_acl_rule_reference_model['name'] = 'my-rule' network_acl_rule_prototype_model = {} network_acl_rule_prototype_model['action'] = 'allow' network_acl_rule_prototype_model[ 'before'] = network_acl_rule_reference_model network_acl_rule_prototype_model['destination'] = '192.168.3.0/24' network_acl_rule_prototype_model['direction'] = 'inbound' network_acl_rule_prototype_model['href'] = href network_acl_rule_prototype_model['id'] = network_acl_rule_id network_acl_rule_prototype_model['ip_version'] = 'ipv4' network_acl_rule_prototype_model['name'] = 'my-rule-2' network_acl_rule_prototype_model['protocol'] = 'icmp' network_acl_rule_prototype_model['source'] = '192.168.3.0/24' network_acl_rule_prototype_model['code'] = 0 network_acl_rule_prototype_model['type'] = 8 network_acl_rule_prototype = network_acl_rule_prototype_model response = service.create_network_acl_rule(network_acl_id, network_acl_rule_prototype)
Response
The action to perform for a packet matching the rule.
Possible values: [
allow
,deny
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the rule was created
The destination IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all destination addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The direction of traffic to match.
Possible values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The IP version for this rule
Possible values: [
ipv4
]The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-rule-1
The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The source IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all source addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The rule that this rule is immediately before. If absent, this is the last rule.
Examples:ViewThe URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-rule-1
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
before
The inclusive upper bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The inclusive lower bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The protocol to enforce.
Possible values: [
tcp
,udp
]The inclusive upper bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
65535
The inclusive lower bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
49152
One of
Status Code
The network ACL rule was created successfully.
An invalid network ACL rule prototype object was provided.
A network ACL with the specified identifier could not be found.
{ "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "inbound-rule-1", "protocol": "all", "source": "0.0.0.0/0" }
Delete a network ACL rule
This request deletes a rule. This operation cannot be reversed.
DELETE /network_acls/{network_acl_id}/rules/{id}
Request
Path Parameters
The network ACL identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteNetworkACLRuleOptions{} options.SetID(ruleID) options.SetNetworkACLID(aclID) response, err := vpcService.DeleteNetworkACLRule(options)
DeleteNetworkAclRuleOptions deleteNetworkAclRuleOptions = new DeleteNetworkAclRuleOptions.Builder() .networkAclId(networkAclId) .id(ruleId) .build(); Response<Void> response = service.deleteNetworkAclRule(deleteNetworkAclRuleOptions).execute();
const response = await vpcService.deleteNetworkAclRule({ networkAclId, id, });
response = service.delete_network_acl_rule(network_acl_id, id)
Retrieve a network ACL rule
This request retrieves a single rule specified by the identifier in the URL.
GET /network_acls/{network_acl_id}/rules/{id}
Request
Path Parameters
The network ACL identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetNetworkACLRuleOptions{} options.SetID(ruleID) options.SetNetworkACLID(aclID) rule, response, err := vpcService.GetNetworkACLRule(options)
GetNetworkAclRuleOptions getNetworkAclRuleOptions = new GetNetworkAclRuleOptions.Builder() .networkAclId(networkAclId) .id(id) .build(); Response<NetworkACLRule> response = service.getNetworkAclRule(getNetworkAclRuleOptions).execute(); NetworkACLRule networkAclRule = response.getResult();
const response = await vpcService.getNetworkAclRule({ networkAclId, id, });
response = service.get_network_acl_rule(network_acl_id, id)
Response
The action to perform for a packet matching the rule.
Possible values: [
allow
,deny
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the rule was created
The destination IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all destination addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The direction of traffic to match.
Possible values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The IP version for this rule
Possible values: [
ipv4
]The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-rule-1
The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The source IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all source addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The rule that this rule is immediately before. If absent, this is the last rule.
Examples:ViewThe URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-rule-1
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
before
The inclusive upper bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The inclusive lower bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The protocol to enforce.
Possible values: [
tcp
,udp
]The inclusive upper bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
65535
The inclusive lower bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
49152
One of
Status Code
The network ACL rule was retrieved successfully.
A network ACL rule with the specified identifier could not be found.
{ "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "allow-all-inbound-rule", "protocol": "all", "source": "0.0.0.0/0" }
Update a network ACL rule
This request updates a rule with the information in a provided rule patch. The rule patch object contains only the information to be updated. The request will fail if the information is not applicable to the rule's protocol.
PATCH /network_acls/{network_acl_id}/rules/{id}
Request
Path Parameters
The network ACL identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The network ACL rule patch
The action to perform for a packet matching the rule.
Allowable values: [
allow
,deny
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The rule to move this rule immediately before.
Specify
null
to move this rule after all existing rules.The ICMP traffic code to match. If set,
type
must also be set.Specify
null
to remove an existing ICMP traffic code.Possible values: 0 ≤ value ≤ 255
The destination IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all destination addresses.Possible values: 7 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$
Example:
192.168.3.2/32
The inclusive upper bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The inclusive lower bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The direction of traffic to match.
Allowable values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The name for this network ACL rule. The name must not be used by another rule for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-rule-1
The protocol to enforce.
Allowable values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The source IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all source addresses.Possible values: 7 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))?$
Example:
192.168.3.2/32
The inclusive upper bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
65535
The inclusive lower bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
49152
The ICMP traffic type to match.
Specify
null
to remove an existing ICMP traffic type value.Possible values: 0 ≤ value ≤ 254
Example:
8
curl -X PATCH "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "inbound-rule-1-updated" }'
options := &vpcv1.UpdateNetworkACLRuleOptions{} options.SetID(ruleID) options.SetNetworkACLID(aclID) options.SetName(name) rule, response, err := vpcService.UpdateNetworkACLRule(options)
UpdateNetworkAclRuleOptions updateNetworkAclRuleOptions = new UpdateNetworkAclRuleOptions.Builder() .networkAclId(networkAclId) .id(id) .name(name) .build(); Response<NetworkACLRule> response = service.updateNetworkAclRule(updateNetworkAclRuleOptions).execute(); NetworkACLRule networkAclRule = response.getResult();
const response = await vpcService.updateNetworkAclRule({ networkAclId, id, name: 'my-network-acl-rule', });
network_acl_rule_patch_before_model = {} network_acl_rule_patch_before_model['id'] = network_acl_rule_id action = 'allow' before = network_acl_rule_patch_before_model code = 0 destination = '192.168.3.2/32' destination_port_max = 22 destination_port_min = 22 direction = 'inbound' name = 'my-rule-2' source = '192.168.3.2/32' source_port_max = 65535 source_port_min = 49152 type = 8 response = service.update_network_acl_rule( network_acl_id, id, action=action, before=before, code=code, destination=destination, destination_port_max=destination_port_max, destination_port_min=destination_port_min, direction=direction, name=name, source=source, source_port_max=source_port_max, source_port_min=source_port_min, type=type, )
Response
The action to perform for a packet matching the rule.
Possible values: [
allow
,deny
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the rule was created
The destination IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all destination addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The direction of traffic to match.
Possible values: [
inbound
,outbound
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The IP version for this rule
Possible values: [
ipv4
]The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-rule-1
The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The source IP address or CIDR block to match. The CIDR block
0.0.0.0/0
matches all source addresses.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The rule that this rule is immediately before. If absent, this is the last rule.
Examples:ViewThe URL for this network ACL rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/network_acls/a4e28308-8ee7-46ab-8108-9f881f22bdbf/rules/8daca77a-4980-4d33-8f3e-7038797be8f9
The unique identifier for this network ACL rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
8daca77a-4980-4d33-8f3e-7038797be8f9
The name for this network ACL rule. The name is unique across all rules for the network ACL.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-rule-1
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
before
The inclusive upper bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The inclusive lower bound of TCP/UDP destination port range
Possible values: 1 ≤ value ≤ 65535
Example:
22
The protocol to enforce.
Possible values: [
tcp
,udp
]The inclusive upper bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
65535
The inclusive lower bound of TCP/UDP source port range
Possible values: 1 ≤ value ≤ 65535
Example:
49152
One of
Status Code
The network ACL rule was updated successfully.
An invalid network ACL rule patch was provided.
A network ACL rule with the specified identifier could not be found.
{ "action": "allow", "created_at": "2019-01-29T06:26:17Z", "destination": "0.0.0.0/0", "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/network_acls/3217cb8b-5368-452a-9399-a84f14fb539d/rules/cb19f11d-0e25-4650-a8ab-f4539da563ee", "id": "cb19f11d-0e25-4650-a8ab-f4539da563ee", "ip_version": "ipv4", "name": "inbound-rule-1-updated", "protocol": "all", "source": "0.0.0.0/0" }
List all security groups
This request lists all security groups in the region. Security groups provide a way to apply IP filtering rules to instances in the associated VPC. With security groups, all traffic is denied by default, and rules added to security groups define which traffic the security group permits. Security group rules are stateful such that reverse traffic in response to allowed traffic is automatically permitted.
GET /security_groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
curl -X GET "$vpc_api_endpoint/v1/security_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSecurityGroupsOptions{} securityGroups, response, err := vpcService.ListSecurityGroups(options)
ListSecurityGroupsOptions listSecurityGroupsOptions = new ListSecurityGroupsOptions.Builder() .build(); Response<SecurityGroupCollection> response = service.listSecurityGroups(listSecurityGroupsOptions).execute(); SecurityGroupCollection securityGroupCollection = response.getResult();
const response = await vpcService.listSecurityGroups();
response = service.list_security_groups()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of security groups
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The security groups were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups?limit=50" }, "limit": 50, "security_groups": [ { "created_at": "2018-12-03T21:13:27Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021", "id": "2d364f0a-a870-42c3-a554-000001092021", "name": "my-security-group-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021/rules/b597cff2-38e8-4e6e-999d-000002158409", "id": "b597cff2-38e8-4e6e-999d-000002158409", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "all", "remote": { "cidr_block": "0.0.0.0/0" } }, { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021/rules/b597cff2-38e8-4e6e-999d-000002158945", "id": "b597cff2-38e8-4e6e-999d-000002158945", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 }, { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021/rules/b597cff2-38e8-4e6e-999d-000002158607", "id": "b597cff2-38e8-4e6e-999d-000002158607", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "all", "remote": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021", "id": "2d364f0a-a870-42c3-a554-000001092021", "name": "my-security-group-1" } } ], "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-1dd56f4c3275", "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275", "name": "my-network-interface", "resource_type": "network_interface" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/210e7530-01a6-485f-a603-47ca070ef3c1", "id": "210e7530-01a6-485f-a603-47ca070ef3c1", "name": "my-vpc", "resource_type": "vpc" } }, { "created_at": "2018-12-06T02:00:33Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421", "id": "2d364f0a-a870-42c3-a554-000001096421", "name": "my-security-group-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421/rules/b597cff2-38e8-4e6e-999d-000002166937", "id": "b597cff2-38e8-4e6e-999d-000002166937", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }, { "direction": "outbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421/rules/b597cff2-38e8-4e6e-999d-000002166993", "id": "b597cff2-38e8-4e6e-999d-000002166993", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "all", "remote": { "cidr_block": "0.0.0.0/0" } }, { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421/rules/b597cff2-38e8-4e6e-999d-000002167157", "id": "b597cff2-38e8-4e6e-999d-000002167157", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "all", "remote": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421", "id": "2d364f0a-a870-42c3-a554-000001096421", "name": "my-security-group-2" } }, { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001096421/rules/b597cff2-38e8-4e6e-999d-000002167167", "id": "b597cff2-38e8-4e6e-999d-000002167167", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" } } ], "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/e402fa1b-96f6-4aa2-a8d7-703aac843651/network_interfaces/7ca88dfb-8962-469d-b1de-1dd56f4c3275", "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275", "name": "my-network-interface", "resource_type": "network_interface" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/6c008092-e04e-40a4-ac4c-880f60e06281", "id": "6c008092-e04e-40a4-ac4c-880f60e06281", "name": "my-vpc-1", "resource_type": "vpc" } } ], "total_count": 2 }
Create a security group
This request creates a new security group from a security group prototype object. The prototype object is structured in the same way as a retrieved security group, and contains the information necessary to create the new security group. If security group rules are included in the prototype object, those rules will be added to the security group. Each security group is scoped to one VPC. Only resources in that VPC can be added to the security group.
POST /security_groups
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The security group prototype object
The VPC this security group will reside in
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
The name for this security group. The name must not be used by another security group for the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-security-group
The resource group to use. If unspecified, the account's default resource group will be used.
The prototype objects for rules to be created for this security group. If unspecified, no rules will be created, resulting in all traffic being denied.
rules
curl -X POST "$vpc_api_endpoint/v1/security_groups?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-security-group-allow-ssh", "rules": [ { "direction": "inbound", "ip_version": "ipv4", "protocol": "tcp", "port_min": 22, "port_max": 22, "remote": { "cidr_block": "0.0.0.0/0" } } ], "vpc": { "id": "31cf397a-286a-4289-a7e7-92f177e7e491" } }'
options := &vpcv1.CreateSecurityGroupOptions{} options.SetVpc(&vpcv1.VPCIdentity{ ID: &vpcID, }) options.SetName(name) sg, response, err := vpcService.CreateSecurityGroup(options)
VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); CreateSecurityGroupOptions createSecurityGroupOptions = new CreateSecurityGroupOptions.Builder() .vpc(vpcIdentityModel) .name("my-security-group") .build(); Response<SecurityGroup> response = service.createSecurityGroup(createSecurityGroupOptions).execute(); SecurityGroup securityGroup = response.getResult();
const vpcIdentityModel = { id: vpcID, }; const params = { vpc: vpcIdentityModel, name: 'my-security-group', }; const response = await vpcService.createSecurityGroup(params);
vpc_identity_model = {} vpc_identity_model['id'] = vpc resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id security_group_rule_protocol_icmp_remote_model = {} security_group_rule_protocol_icmp_remote_model[ 'address'] = '192.168.3.4' security_group_rule_prototype_model = {} security_group_rule_prototype_model['direction'] = 'inbound' security_group_rule_prototype_model['ip_version'] = 'ipv4' security_group_rule_prototype_model['protocol'] = 'icmp' security_group_rule_prototype_model[ 'remote'] = security_group_rule_protocol_icmp_remote_model security_group_rule_prototype_model['code'] = 0 security_group_rule_prototype_model['type'] = 8 vpc = vpc_identity_model name = 'my-security_group' resource_group = resource_group_identity_model rules = [security_group_rule_prototype_model] response = service.create_security_group( vpc, name=name, resource_group=resource_group, rules=rules, )
Response
The date and time that this security group was created
The security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
The resource group for this security group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The rules for this security group. If no rules exist, all traffic will be denied.
rules
The targets for this security group.
targets
The VPC this security group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The security group was created successfully.
An invalid security group prototype object was provided.
{ "created_at": "2018-12-07T17:52:13Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037", "id": "2d364f0a-a870-42c3-a554-000001099037", "name": "my-security-group-allow-ssh", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } } ], "targets": [], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/31cf397a-286a-4289-a7e7-92f177e7e491", "id": "31cf397a-286a-4289-a7e7-92f177e7e491", "name": "my-vpc-2", "resource_type": "vpc" } }
Delete a security group
This request deletes a security group. A security group cannot be deleted if it is referenced by any security group targets or rules. Additionally, a VPC's default security group cannot be deleted. This operation cannot be reversed.
DELETE /security_groups/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/security_groups/$security_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSecurityGroupOptions{} options.SetID(id) response, err := vpcService.DeleteSecurityGroup(options)
DeleteSecurityGroupRuleOptions deleteSecurityGroupRuleOptions = new DeleteSecurityGroupRuleOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<Void> response = service.deleteSecurityGroupRule(deleteSecurityGroupRuleOptions).execute();
const response = await vpcService.deleteSecurityGroup({ id });
response = service.delete_security_group(id)
Retrieve a security group
This request retrieves a single security group specified by the identifier in the URL path.
GET /security_groups/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/security_groups/$security_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSecurityGroupOptions{} options.SetID(id) sg, response, err := vpcService.GetSecurityGroup(options)
GetSecurityGroupOptions getSecurityGroupOptions = new GetSecurityGroupOptions.Builder() .id(id) .build(); Response<SecurityGroup> response = service.getSecurityGroup(getSecurityGroupOptions).execute(); SecurityGroup securityGroup = response.getResult();
const response = await vpcService.getSecurityGroup({ id });
response = service.get_security_group(id)
Response
The date and time that this security group was created
The security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
The resource group for this security group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The rules for this security group. If no rules exist, all traffic will be denied.
rules
The targets for this security group.
targets
The VPC this security group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The security group was retrieved successfully.
A security group with the specified identifier could not be found.
{ "created_at": "2018-12-07T17:52:13Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037", "id": "2d364f0a-a870-42c3-a554-000001099037", "name": "my-security-group-allow-ssh", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }, { "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173005", "id": "b597cff2-38e8-4e6e-999d-000002173005", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 } ], "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/31cf397a-286a-4289-a7e7-92f177e7e491", "id": "31cf397a-286a-4289-a7e7-92f177e7e491", "name": "my-vpc-2", "resource_type": "vpc" } }
Update a security group
This request updates a security group with the information provided in a security group patch object. The security group patch object is structured in the same way as a retrieved security group and contains only the information to be updated.
PATCH /security_groups/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The security group patch.
The name for this security group. The name must not be used by another security group for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-security-group
curl -X PATCH "$vpc_api_endpoint/v1/security_groups/$security_group_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-security-group-allow-ssh-2" }'
options := &vpcv1.UpdateSecurityGroupOptions{} options.SetID(id) options.SetName(name) sg, response, err := vpcService.UpdateSecurityGroup(options)
UpdateSecurityGroupOptions updateSecurityGroupOptions = new UpdateSecurityGroupOptions.Builder() .id(id) .name(name) .build(); Response<SecurityGroup> response = service.updateSecurityGroup(updateSecurityGroupOptions).execute(); SecurityGroup securityGroup = response.getResult();
const response = await vpcService.updateSecurityGroup({ id, name: 'my-security-group', });
response = service.update_security_group( id, name=name, )
Response
The date and time that this security group was created
The security group's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The security group's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The unique identifier for this security group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271
The name for this security group. The name is unique across all security groups for the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-security-group
The resource group for this security group
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The rules for this security group. If no rules exist, all traffic will be denied.
rules
The targets for this security group.
targets
The VPC this security group resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The security group was updated successfully.
An invalid security group patch was provided.
A security group with the specified identifier could not be found.
{ "created_at": "2018-12-07T17:52:13Z", "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037", "id": "2d364f0a-a870-42c3-a554-000001099037", "name": "my-security-group-allow-ssh-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }, { "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173005", "id": "b597cff2-38e8-4e6e-999d-000002173005", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 } ], "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/31cf397a-286a-4289-a7e7-92f177e7e491", "id": "31cf397a-286a-4289-a7e7-92f177e7e491", "name": "my-vpc-2", "resource_type": "vpc" } }
List all rules in a security group
This request lists all rules in a security group. These rules define what traffic the security group permits. Security group rules are stateful, such that reverse traffic in response to allowed traffic is automatically permitted.
GET /security_groups/{security_group_id}/rules
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSecurityGroupRulesOptions{} options.SetSecurityGroupID(id) rules, response, err := vpcService.ListSecurityGroupRules(options)
ListSecurityGroupRulesOptions listSecurityGroupRulesOptions = new ListSecurityGroupRulesOptions.Builder() .securityGroupId(securityGroupId) .build(); Response<SecurityGroupRuleCollection> response = service.listSecurityGroupRules(listSecurityGroupRulesOptions).execute(); SecurityGroupRuleCollection securityGroupRuleCollection = response.getResult();
const response = await vpcService.listSecurityGroupRules({ securityGroupId });
response = service.list_security_group_rules(security_group_id)
Response
Collection of rules in a security group
Array of rules
rules
Status Code
The security group rules were retrieved successfully.
A security group with the specified identifier could not be found.
{ "rules": [ { "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }, { "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173027", "id": "b597cff2-38e8-4e6e-999d-000002173027", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 } ] }
Create a rule for a security group
This request creates a new security group rule from a security group rule prototype object. The prototype object is structured in the same way as a retrieved security group rule and contains the information necessary to create the rule. As part of creating a new rule in a security group, the rule is applied to all the networking interfaces in the security group. Rules specify which IP traffic a security group will allow. Security group rules are stateful, such that reverse traffic in response to allowed traffic is automatically permitted. A rule allowing inbound TCP traffic on port 80 also allows outbound TCP traffic on port 80 without the need for an additional rule.
POST /security_groups/{security_group_id}/rules
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The properties of the security group rule to be created.
The direction of traffic to enforce.
Allowable values: [
inbound
,outbound
]Example:
inbound
The protocol to enforce.
Allowable values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Allowable values: [
ipv4
]Default:
ipv4
Example:
ipv4
The local IP address or range of local IP addresses to which this rule will allow inbound traffic (or from which, for outbound traffic)
If unspecified, a CIDR block of
0.0.0.0/0
will be used to allow traffic to all local IP addresses (or from all local IP addresses, for outbound rules).The remote IP addresses or security groups from which this rule will allow traffic (or to which, for outbound rules). Can be specified as an IP address, a CIDR block, or a security group within the VPC.
If unspecified, a CIDR block of
0.0.0.0/0
will be used to allow traffic from any source (or to any destination, for outbound rules).A rule allowing traffic for all supported protocols.
The direction of traffic to enforce.
Allowable values: [
inbound
,outbound
]Example:
inbound
The protocol to enforce.
Allowable values: [
all
]The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Allowable values: [
ipv4
]Example:
ipv4
One of
curl -X POST "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "direction": "inbound", "code": 0, "ip_version": "ipv4", "local": { "address": "192.168.11.12" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 }'
options := &vpcv1.CreateSecurityGroupRuleOptions{} options.SetSecurityGroupID(sgID) options.SetSecurityGroupRulePrototype(&vpcv1.SecurityGroupRulePrototype{ Direction: core.StringPtr("inbound"), Protocol: core.StringPtr("all"), IpVersion: core.StringPtr("ipv4"), }) rule, response, err := vpcService.CreateSecurityGroupRule(options)
SecurityGroupRulePrototypeSecurityGroupRuleProtocolICMP securityGroupRulePrototypeModel = new SecurityGroupRulePrototypeSecurityGroupRuleProtocolICMP.Builder() .direction("inbound") .build(); CreateSecurityGroupRuleOptions createSecurityGroupRuleOptions = new CreateSecurityGroupRuleOptions.Builder() .securityGroupId(securityGroupId) .securityGroupRulePrototype(securityGroupRulePrototypeModel) .build(); Response<SecurityGroupRule> response = service.createSecurityGroupRule(createSecurityGroupRuleOptions).execute(); SecurityGroupRule securityGroupRule = response.getResult();
const securityGroupRulePrototypeRemoteModel = { address: '192.168.3.4', }; const securityGroupRulePrototypeModel = { direction: 'inbound', ip_version: 'ipv4', protocol: 'tcp', remote: securityGroupRulePrototypeRemoteModel, code: 0, type: 8, }; const params = { securityGroupId, securityGroupRulePrototype: securityGroupRulePrototypeModel, }; const response = await vpcService.createSecurityGroupRule(params);
security_group_rule_protocol_icmp_remote_model = {} security_group_rule_protocol_icmp_remote_model[ 'address'] = '192.168.3.4' security_group_rule_prototype_model = {} security_group_rule_prototype_model['direction'] = 'inbound' security_group_rule_prototype_model['ip_version'] = 'ipv4' security_group_rule_prototype_model['protocol'] = 'icmp' security_group_rule_prototype_model[ 'remote'] = security_group_rule_protocol_icmp_remote_model security_group_rule_prototype_model['code'] = 0 security_group_rule_prototype_model['type'] = 8 security_group_id = security_group_id security_group_rule_prototype = security_group_rule_prototype_model response = service.create_security_group_rule( security_group_id, security_group_rule_prototype)
Response
The direction of traffic to enforce.
Possible values: [
inbound
,outbound
]Example:
inbound
The URL for this security group rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271/rules/6f2a6efe-21e2-401c-b237-620aa26ba16a
The unique identifier for this security group rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
6f2a6efe-21e2-401c-b237-620aa26ba16a
The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Possible values: [
ipv4
]Example:
ipv4
The local IP address or range of local IP addresses to which this rule will allow inbound traffic (or from which, for outbound traffic). A CIDR block of
0.0.0.0/0
allows traffic to all local IP addresses (or from all local IP addresses, for outbound rules).The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The remote IP addresses or security groups from which this rule allows traffic (or to which, for outbound rules). A CIDR block of
0.0.0.0/0
allows traffic from any source (or to any destination, for outbound rules).A rule allowing traffic for all supported protocols.
The protocol to enforce.
Possible values: [
all
]
One of
Status Code
The security group rule was created successfully.
An invalid security group rule prototype object was provided.
A security group with the specified identifier could not be found.
{ "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173027", "id": "b597cff2-38e8-4e6e-999d-000002173027", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "protocol": "icmp", "remote": { "cidr_block": "0.0.0.0/0" }, "type": 8 }
Delete a security group rule
This request deletes a security group rule. This operation cannot be reversed. Removing a security group rule will not end existing connections allowed by that rule.
DELETE /security_groups/{security_group_id}/rules/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteSecurityGroupRuleOptions{} options.SetSecurityGroupID(sgID) options.SetID(sgRuleID) response, err := vpcService.DeleteSecurityGroupRule(options)
DeleteSecurityGroupRuleOptions deleteSecurityGroupRuleOptions = new DeleteSecurityGroupRuleOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<Void> response = service.deleteSecurityGroupRule(deleteSecurityGroupRuleOptions).execute();
const response = await vpcService.deleteSecurityGroupRule({ securityGroupId, id, });
response = service.delete_security_group_rule(security_group_id, id)
Retrieve a security group rule
This request retrieves a single security group rule specified by the identifier in the URL path.
GET /security_groups/{security_group_id}/rules/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSecurityGroupRuleOptions{} options.SetSecurityGroupID(sgID) options.SetID(sgRuleID) rule, response, err := vpcService.GetSecurityGroupRule(options)
GetSecurityGroupRuleOptions getSecurityGroupRuleOptions = new GetSecurityGroupRuleOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<SecurityGroupRule> response = service.getSecurityGroupRule(getSecurityGroupRuleOptions).execute(); SecurityGroupRule securityGroupRule = response.getResult();
const response = await vpcService.getSecurityGroupRule({ securityGroupId, id, });
response = service.get_security_group_rule(security_group_id, id)
Response
The direction of traffic to enforce.
Possible values: [
inbound
,outbound
]Example:
inbound
The URL for this security group rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271/rules/6f2a6efe-21e2-401c-b237-620aa26ba16a
The unique identifier for this security group rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
6f2a6efe-21e2-401c-b237-620aa26ba16a
The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Possible values: [
ipv4
]Example:
ipv4
The local IP address or range of local IP addresses to which this rule will allow inbound traffic (or from which, for outbound traffic). A CIDR block of
0.0.0.0/0
allows traffic to all local IP addresses (or from all local IP addresses, for outbound rules).The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The remote IP addresses or security groups from which this rule allows traffic (or to which, for outbound rules). A CIDR block of
0.0.0.0/0
allows traffic from any source (or to any destination, for outbound rules).A rule allowing traffic for all supported protocols.
The protocol to enforce.
Possible values: [
all
]
One of
Status Code
The rule was retrieved successfully.
A rule with the specified identifier could not be found.
{ "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002172691", "id": "b597cff2-38e8-4e6e-999d-000002172691", "ip_version": "ipv4", "local": { "cidr_block": "0.0.0.0/0" }, "port_max": 22, "port_min": 22, "protocol": "tcp", "remote": { "cidr_block": "0.0.0.0/0" } }
Update a security group rule
This request updates a security group rule with the information in a provided rule patch object. The rule patch object contains only the information to be updated. The request will fail if the information is not applicable to the rule's protocol.
PATCH /security_groups/{security_group_id}/rules/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The security group rule patch.
The ICMP traffic code to allow. If set,
type
must also be set.Specify
null
to remove an existing ICMP traffic code.Possible values: 0 ≤ value ≤ 255
The direction of traffic to enforce.
Allowable values: [
inbound
,outbound
]Example:
inbound
The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Allowable values: [
ipv4
]Example:
ipv4
The local IP address or range of local IP addresses to which this rule will allow inbound traffic (or from which, for outbound traffic). Can be specified as an IP address or a CIDR block.
Specify a CIDR block of
0.0.0.0/0
to allow traffic to all local IP addresses (or from all local IP addresses, for outbound rules).The inclusive upper bound of the protocol destination port range. If set,
port_min
must also be set, and must not be larger.Specify
null
to remove an existing upper bound.Possible values: 1 ≤ value ≤ 65535
Example:
22
The inclusive lower bound of the protocol destination port range. If set,
port_max
must also be set, and must not be smaller.Specify
null
to remove an existing lower bound.Possible values: 1 ≤ value ≤ 65535
Example:
22
The remote IP addresses or security groups from which this rule will allow traffic (or to which, for outbound rules). Can be specified as an IP address, a CIDR block, or a security group. A CIDR block of
0.0.0.0/0
will allow traffic from any source (or to any destination, for outbound rules).The ICMP traffic type to allow.
Specify
null
to remove an existing ICMP traffic type value.Possible values: 0 ≤ value ≤ 254
Example:
8
curl -X PATCH "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "local": { "address": "192.168.11.24" }, "remote": { "cidr_block": "9.10.0.0/16" } }'
options := &vpcv1.UpdateSecurityGroupRuleOptions{} options.SetSecurityGroupID(sgID) options.SetID(sgRuleID) options.SetRemote(&vpcv1.SecurityGroupRulePatchRemote{ Address: &ip, }) rule, response, err := vpcService.UpdateSecurityGroupRule(options)
UpdateSecurityGroupRuleOptions updateSecurityGroupRuleOptions = new UpdateSecurityGroupRuleOptions.Builder() .securityGroupId(securityGroupId) .id(id) .name(name) .build(); Response<SecurityGroupRule> response = service.updateSecurityGroupRule(updateSecurityGroupRuleOptions).execute(); SecurityGroupRule securityGroupRule = response.getResult();
const params = { securityGroupId, id, remote: { address: '192.168.3.4', }, }; const response = await vpcService.updateSecurityGroupRule(params);
security_group_rule_patch_remote_model = {} security_group_rule_patch_remote_model['address'] = '192.168.3.4' code = 0 direction = 'inbound' ip_version = 'ipv4' port_max = 22 port_min = 22 remote = security_group_rule_patch_remote_model type = 8 response = service.update_security_group_rule( security_group_id, id, code=code, direction=direction, ip_version=ip_version, port_max=port_max, port_min=port_min, remote=remote, type=type, )
Response
The direction of traffic to enforce.
Possible values: [
inbound
,outbound
]Example:
inbound
The URL for this security group rule
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271/rules/6f2a6efe-21e2-401c-b237-620aa26ba16a
The unique identifier for this security group rule
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
6f2a6efe-21e2-401c-b237-620aa26ba16a
The IP version to enforce. The format of
local.address
,remote.address
,local.cidr_block
orremote.cidr_block
must match this property, if they are used.If
remote
references a security group, then this rule only applies to IP addresses (network interfaces) in that group matching this IP version.Possible values: [
ipv4
]Example:
ipv4
The local IP address or range of local IP addresses to which this rule will allow inbound traffic (or from which, for outbound traffic). A CIDR block of
0.0.0.0/0
allows traffic to all local IP addresses (or from all local IP addresses, for outbound rules).The protocol to enforce.
Possible values: [
all
,icmp
,tcp
,udp
]Example:
tcp
The remote IP addresses or security groups from which this rule allows traffic (or to which, for outbound rules). A CIDR block of
0.0.0.0/0
allows traffic from any source (or to any destination, for outbound rules).A rule allowing traffic for all supported protocols.
The protocol to enforce.
Possible values: [
all
]
One of
Status Code
The security group rule was updated successfully.
An invalid security group rule patch was provided.
A rule with the specified identifier could not be found.
{ "code": 0, "direction": "inbound", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001099037/rules/b597cff2-38e8-4e6e-999d-000002173027", "id": "b597cff2-38e8-4e6e-999d-000002173027", "ip_version": "ipv4", "local": { "address": "10.10.1.5" }, "protocol": "icmp", "remote": { "cidr_block": "9.10.0.0/16" }, "type": 8 }
List all targets associated with a security group
This request lists all targets associated with a security group, to which the rules in the security group are applied.
GET /security_groups/{security_group_id}/targets
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListSecurityGroupTargetsOptions{} options.SetSecurityGroupID(id) targets, response, err := vpcService.ListSecurityGroupTargets(options)
ListSecurityGroupTargetsOptions listSecurityGroupTargetsOptions = new ListSecurityGroupTargetsOptions.Builder() .securityGroupId(securityGroupId) .build(); Response<SecurityGroupTargetCollection> response = service.listSecurityGroupTargets(listSecurityGroupTargetsOptions).execute(); SecurityGroupTargetCollection targetCollection = response.getResult();
const response = await vpcService.listSecurityGroupTargets({ securityGroupId });
response = service.list_security_group_targets( security_group_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271/targets?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of targets for this security group.
targets
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271/targets?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The targets were retrieved successfully.
A security group with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/2d364f0a-a870-42c3-a554-000001092021/targets?limit=50" }, "limit": 50, "targets": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" } ], "total_count": 1 }
Remove a target from a security group
This request removes a target from a security group. For this request to succeed, the target must be attached to at least one other security group. The specified target identifier can be:
- A bare metal server network interface identifier
- A virtual network interface identifier
- A VPN server identifier
- A load balancer identifier
- An endpoint gateway identifier
- An instance network interface identifier
Security groups are stateful, so any changes to a target's security groups are applied to new connections. Existing connections are not affected.
DELETE /security_groups/{security_group_id}/targets/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.endpoint-gateway.endpoint-gateway.update
Generated when
target
specifies an endpoint gatewayis.instance.network-interface.update
Generated when
target
specifies an instance network interfaceis.bare-metal-server.network-interface.update
Generated when
target
specifies a bare metal server network interfaceis.load-balancer.load-balancer.update
Generated when
target
specifies a load balanceris.vpn-server.vpn-server.update
Generated when
target
specifies a VPN serveris.security-group.security-group.detach
is.virtual-network-interface.virtual-network-interface.detach
Generated when
target
specifies a virtual network interface
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The security group target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.RemoveSecurityGroupTargetOptions{} options.SetSecurityGroupID(id) options.SetID(targetID) response, err := vpcService.RemoveSecurityGroupTarget(options)
RemoveSecurityGroupTargetOptions removeSecurityGroupTargetOptions = new RemoveSecurityGroupTargetOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<Void> response = service.removeSecurityGroupTarget(removeSecurityGroupTargetOptions).execute();
const response = await vpcService.deleteSecurityGroupTarget({ id, securityGroupId, });
response = service.remove_security_group_target( security_group_id, id)
Response
Status Code
The target was successfully removed from the security group.
The specified target was not in the specified security group.
The specified target is not attached to any other security groups.
The specified target cannot be removed from the security group in its current state. (Applicable to application load balancer targets that do not have an
active
provisioning status.)
No Sample Response
Retrieve a security group target
This request retrieves a single target specified by the identifier in the URL path. The target must be an existing target of the security group.
GET /security_groups/{security_group_id}/targets/{id}
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The security group target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetSecurityGroupTargetOptions{} options.SetSecurityGroupID(id) options.SetID(targetID) target, response, err := vpcService.GetSecurityGroupTarget(options)
GetSecurityGroupTargetOptions getSecurityGroupTargetOptions = new GetSecurityGroupTargetOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<SecurityGroupTargetReference> response = service.getSecurityGroupTarget(getSecurityGroupTargetOptions).execute(); SecurityGroupTargetReference target = response.getResult();
const response = await vpcService.getSecurityGroupTarget({ securityGroupId, id, });
response = service.get_security_group_target( security_group_id, id)
Response
A target of this security group.
The resources supported by this property may expand in the future.
The URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The target was retrieved successfully.
The specified target or security group could not be found.
{ "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" }
Add a target to a security group
This request adds a resource to an existing security group. The specified target identifier can be:
- A bare metal server network interface identifier
- A virtual network interface identifier
- A VPN server identifier
- A load balancer identifier
- An endpoint gateway identifier
- An instance network interface identifier
When a target is added to a security group, the security group rules are applied to the target. A request body is not required, and if provided, is ignored.
PUT /security_groups/{security_group_id}/targets/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.endpoint-gateway.endpoint-gateway.update
Generated when
target
specifies an endpoint gatewayis.instance.network-interface.update
Generated when
target
specifies an instance network interfaceis.bare-metal-server.network-interface.update
Generated when
target
specifies a bare metal server network interfaceis.load-balancer.load-balancer.update
Generated when
target
specifies a load balanceris.vpn-server.vpn-server.update
Generated when
target
specifies a VPN serveris.security-group.security-group.attach
is.virtual-network-interface.virtual-network-interface.attach
Generated when
target
specifies a virtual network interface
Request
Path Parameters
The security group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The security group target identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/security_groups/$security_group_id/targets/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.AddSecurityGroupTargetOptions{} options.SetSecurityGroupID(id) options.SetID(targetID) target, response, err := vpcService.AddSecurityGroupTarget(options)
AddSecurityGroupTargetOptions addSecurityGroupTargetOptions = new AddSecurityGroupTargetOptions.Builder() .securityGroupId(securityGroupId) .id(id) .build(); Response<SecurityGroupTargetReference> response = service.addSecurityGroupTarget(addSecurityGroupTargetOptions).execute(); SecurityGroupTargetReference target = response.getResult();
const response = await vpcService.addSecurityGroupTarget({ securityGroupId, id, });
response = service.add_security_group_target( security_group_id, id)
Response
A target of this security group.
The resources supported by this property may expand in the future.
The URL for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+/network_interfaces/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The unique identifier for this instance network interface.
If this instance 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.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-10c02d81-0ecb-4dc5-897d-28392913b81e
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
Status Code
The specified target is already in the security group.
The target was successfully added to the security group
The specified target is not in the same VPC, or has reached its security group limit.
The specified target or security group could not be found.
The specified target cannot be updated in its current state.
Applicable to application load balancer targets that do not have an
active
provisioning status.
{ "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" }
{ "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/3b2669a2-4c2b-4003-bc91-1b81f1326267/network_interfaces/f2bc9157-57ed-426f-b8cb-d8555d1437bd", "id": "f2bc9157-57ed-426f-b8cb-d8555d1437bd", "name": "my-primary-network-interface", "resource_type": "network_interface" }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/ike_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListIkePoliciesOptions() ikePolicies, response, err = vpcService.ListIkePolicies(options)
ListIkePoliciesOptions listIkePoliciesOptions = new ListIkePoliciesOptions.Builder() .limit(Long.valueOf("10")) .build(); Response<IKEPolicyCollection> response = service.listIkePolicies(listIkePoliciesOptions).execute(); IKEPolicyCollection ikePolicyCollectionResult = response.getResult();
const response = await vpcService.listIkePolicies();
response = service.list_ike_policies()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies?limit=20
first
Collection of IKE policies
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The IKE policies were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies?limit=50" }, "ike_policies": [ { "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:27:58.95704Z", "dh_group": 14, "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d", "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d", "ike_version": 1, "key_lifetime": 28800, "name": "my-ike-policy-0", "negotiation_mode": "main", "resource_group": { "href": "https://resource-manager.bluemix.net/v1/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "ike_policy" }, { "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:26:24.475125Z", "dh_group": 14, "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148", "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148", "ike_version": 1, "key_lifetime": 28800, "name": "my-ike-policy-1", "negotiation_mode": "main", "resource_group": { "href": "https://resource-manager.bluemix.net/v1/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "ike_policy" } ], "limit": 50, "total_count": 2 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The IKE policy prototype object.
The authentication algorithm
Allowable values: [
sha256
,sha384
,sha512
]The Diffie-Hellman group
Allowable values: [
14
,15
,16
,17
,18
,19
,20
,21
,22
,23
,24
,31
]The encryption algorithm
Allowable values: [
aes128
,aes192
,aes256
]The IKE protocol version
Allowable values: [
1
,2
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Default:
28800
Example:
28800
The name for this IKE policy. The name must not be used by another IKE policies in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ike-policy
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/ike_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "authentication_algorithm": "sha256", "dh_group": 14, "encryption_algorithm": "aes256", "ike_version": 1, "key_lifetime": 28800, "name": "my-ike-policy-1", "resource_group": { "id": "4bbce614c13444cd8fc5e7e878ef8e21" } }'
options := &vpcv1.CreateIkePolicyOptions{} options.SetName(name) options.SetAuthenticationAlgorithm("sha256") options.SetDhGroup(14) options.SetEncryptionAlgorithm("aes256") options.SetIkeVersion(1) ikePolicy, response, err := vpcService.CreateIkePolicy(options)
CreateIkePolicyOptions createIkePolicyOptions = new CreateIkePolicyOptions.Builder() .authenticationAlgorithm("sha256") .dhGroup(Long.valueOf("14")) .encryptionAlgorithm("aes256") .ikeVersion(Long.valueOf("1")) .name("my-ike-policy") .build(); Response<IKEPolicy> response = service.createIkePolicy(createIkePolicyOptions).execute(); IKEPolicy ikePolicyResult = response.getResult();
const params = { authenticationAlgorithm: 'sha256', dhGroup: 14, encryptionAlgorithm: 'aes256', ikeVersion: 1, name: 'my-ike-policy', }; const response = await vpcService.createIkePolicy(params);
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id authentication_algorithm = 'sha256' dh_group = 14 encryption_algorithm = 'aes256' ike_version = 1 key_lifetime = 28800 name = 'my-ike-policy' resource_group = resource_group_identity_model response = service.create_ike_policy( authentication_algorithm, dh_group, encryption_algorithm, ike_version, key_lifetime=key_lifetime, name=name, resource_group=resource_group, )
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedPossible values: [
md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IKE policy.
The date and time that this IKE policy was created
The Diffie-Hellman group
Groups
2
and5
have been deprecatedPossible values: [
14
,15
,16
,17
,18
,19
,2
,20
,21
,22
,23
,24
,31
,5
]The encryption algorithm
The
triple_des
algorithm has been deprecatedPossible values: [
aes128
,aes192
,aes256
,triple_des
]The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The IKE protocol version
Possible values: [
1
,2
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
28800
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ike-policy
The IKE negotiation mode. Only
main
is supported.Possible values: [
main
]The resource group for this IKE policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The IKE policy was created successfully.
An invalid IKE policy prototype object was provided.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:26:24.475125Z", "dh_group": 14, "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148", "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148", "ike_version": 1, "key_lifetime": 28800, "name": "my-ike-policy-1", "negotiation_mode": "main", "resource_group": { "href": "https://resource-manager.bluemix.net/v1/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "ike_policy" }
Delete an IKE policy
This request deletes an IKE policy. This operation cannot be reversed. For this request to succeed, there must not be any VPN gateway connections using this policy.
DELETE /ike_policies/{id}
Request
Path Parameters
The IKE policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteIkePolicyOptions(id) response, err := vpcService.DeleteIkePolicy(options)
DeleteIkePolicyOptions deleteIkePolicyOptions = new DeleteIkePolicyOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteIkePolicy(deleteIkePolicyOptions).execute();
const response = await vpcService.deleteIkePolicy({ id });
response = service.delete_ike_policy(id)
Retrieve an IKE policy
This request retrieves a single IKE policy specified by the identifier in the URL.
GET /ike_policies/{id}
Request
Path Parameters
The IKE policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetIkePolicyOptions(id) ikePolicy, response, err := vpcService.GetIkePolicy(options)
GetIkePolicyOptions getIkePolicyOptions = new GetIkePolicyOptions.Builder() .id(id) .build(); Response<IKEPolicy> response = service.getIkePolicy(getIkePolicyOptions).execute(); IKEPolicy ikePolicyResult = response.getResult();
const response = await vpcService.getIkePolicy({ id });
response = service.get_ike_policy(id)
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedPossible values: [
md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IKE policy.
The date and time that this IKE policy was created
The Diffie-Hellman group
Groups
2
and5
have been deprecatedPossible values: [
14
,15
,16
,17
,18
,19
,2
,20
,21
,22
,23
,24
,31
,5
]The encryption algorithm
The
triple_des
algorithm has been deprecatedPossible values: [
aes128
,aes192
,aes256
,triple_des
]The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The IKE protocol version
Possible values: [
1
,2
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
28800
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ike-policy
The IKE negotiation mode. Only
main
is supported.Possible values: [
main
]The resource group for this IKE policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The IKE policy was retrieved successfully.
An IKE policy with the specified identifier could not be found.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:26:24.475125Z", "dh_group": 14, "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148", "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148", "ike_version": 1, "key_lifetime": 28800, "name": "my-ike-policy-1", "negotiation_mode": "main", "resource_group": { "href": "https://resource-manager.stage1.bluemix.net/v1/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "ike_policy" }
Update an IKE policy
This request updates the properties of an existing IKE policy.
PATCH /ike_policies/{id}
Request
Path Parameters
The IKE policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The IKE policy patch.
The authentication algorithm
Allowable values: [
sha256
,sha384
,sha512
]The Diffie-Hellman group
Allowable values: [
14
,15
,16
,17
,18
,19
,20
,21
,22
,23
,24
,31
]The encryption algorithm
Allowable values: [
aes128
,aes192
,aes256
]The IKE protocol version
Allowable values: [
1
,2
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
28800
The name for this IKE policy. The name must not be used by another IKE policy in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ike-policy
curl -X PATCH "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-new-ike-policy" }'
options := &vpcv1.UpdateIkePolicyOptions{ ID: &id, DhGroup: &dhGroup, Name: &name, } ikePolicy, response, err := vpcService.UpdateIkePolicy(options)
UpdateIkePolicyOptions updateIkePolicyOptions = new UpdateIkePolicyOptions.Builder() .id(id) .name("my-ike-policy") .authenticationAlgorithm("sha256") .dhGroup(Long.valueOf("14")) .encryptionAlgorithm("aes256") .ikeVersion(Long.valueOf("1")) .build(); Response<IKEPolicy> response = service.updateIkePolicy(updateIkePolicyOptions).execute(); IKEPolicy ikePolicyResult = response.getResult();
const response = await vpcService.updateIkePolicy({ id, name: 'my-ike-policy', });
authentication_algorithm = 'sha256' dh_group = 14 encryption_algorithm = 'aes256' ike_version = 1 key_lifetime = 28800 name = 'my-ike-policy' response = service.update_ike_policy( id, authentication_algorithm=authentication_algorithm, dh_group=dh_group, encryption_algorithm=encryption_algorithm, ike_version=ike_version, key_lifetime=key_lifetime, name=name, )
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedPossible values: [
md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IKE policy.
The date and time that this IKE policy was created
The Diffie-Hellman group
Groups
2
and5
have been deprecatedPossible values: [
14
,15
,16
,17
,18
,19
,2
,20
,21
,22
,23
,24
,31
,5
]The encryption algorithm
The
triple_des
algorithm has been deprecatedPossible values: [
aes128
,aes192
,aes256
,triple_des
]The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The IKE protocol version
Possible values: [
1
,2
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
28800
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ike-policy
The IKE negotiation mode. Only
main
is supported.Possible values: [
main
]The resource group for this IKE policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The IKE policy was updated successfully.
An invalid IKE policy patch was provided.
An IKE policy with the specified identifier could not be found.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:26:24.475125Z", "dh_group": 14, "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148", "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148", "ike_version": 1, "key_lifetime": 28800, "name": "my-new-ike-policy", "negotiation_mode": "main", "resource_group": { "href": "https://resource-manager.bluemix.net/v1/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "ike_policy" }
List all VPN gateway connections that use a specified IKE policy
This request lists all VPN gateway connections that use a policy
GET /ike_policies/{id}/connections
Request
Path Parameters
The IKE policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id/connections?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListIkePolicyConnectionsOptions{ ID: &id, } connections, response, err = vpcService.ListIkePolicyConnections(options)
ListIkePolicyConnectionsOptions listIkePolicyConnectionsOptions = new ListIkePolicyConnectionsOptions.Builder() .id(id) .build(); Response<VPNGatewayConnectionCollection> response = service.listIkePolicyConnections(listIkePolicyConnectionsOptions).execute(); VPNGatewayConnectionCollection vpnGatewayConnectionCollectionResult = response.getResult();
const response = await vpcService.listIkePolicyConnections({ id });
response = service.list_ike_policy_connections(id)
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/ipsec_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListIpsecPoliciesOptions{} ipsecPolicies, response, err := vpcService.ListIpsecPolicies(options)
ListIpsecPoliciesOptions listIpsecPoliciesOptions = new ListIpsecPoliciesOptions.Builder() .build(); Response<IPsecPolicyCollection> response = service.listIpsecPolicies(listIpsecPoliciesOptions).execute(); IPsecPolicyCollection iPsecPolicyCollection = response.getResult();
const response = await vpcService.listIpsecPolicies();
response = service.list_ipsec_policies()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies?limit=20
first
Collection of IPsec policies
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The IPsec policies were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies?limit=50" }, "ipsec_policies": [ { "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:34:16.961597Z", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "key_lifetime": 28800, "name": "my-ipsec-policy-1", "pfs": "disabled", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "ipsec_policy", "transform_protocol": "esp" }, { "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:34:08.719912Z", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/a4c47690-bc52-45df-9bbd-a1f2b814a8ac", "id": "a4c47690-bc52-45df-9bbd-a1f2b814a8ac", "key_lifetime": 28800, "name": "my-ipsec-policy-2", "pfs": "disabled", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "ipsec_policy", "transform_protocol": "esp" } ], "limit": 50, "total_count": 2 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The IPsec policy prototype object.
The authentication algorithm
Must be
disabled
if and only if theencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Allowable values: [
disabled
,sha256
,sha384
,sha512
]The encryption algorithm
The
authentication_algorithm
must bedisabled
if and only ifencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Allowable values: [
aes128
,aes128gcm16
,aes192
,aes192gcm16
,aes256
,aes256gcm16
]Perfect Forward Secrecy
Allowable values: [
disabled
,group_14
,group_15
,group_16
,group_17
,group_18
,group_19
,group_20
,group_21
,group_22
,group_23
,group_24
,group_31
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Default:
3600
Example:
3600
The name for this IPsec policy. The name must not be used by another IPsec policies in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ipsec-policy
The resource group to use. If unspecified, the account's default resource group will be used.
curl -X POST "$vpc_api_endpoint/v1/ipsec_policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "authentication_algorithm": "sha256", "encryption_algorithm": "aes256", "key_lifetime": 28800, "name": "my-ipsec-policy-2", "pfs": "disabled", "resource_group": { "id": "3fad3f2204eb4998c3964d254ffcd771" } }'
options := &vpcv1.CreateIpsecPolicyOptions{} options.SetName(name) options.SetAuthenticationAlgorithm("sha256") options.SetEncryptionAlgorithm("aes256") options.SetPfs("disabled") ipsecPolicy, response, err := vpcService.CreateIpsecPolicy(options)
CreateIpsecPolicyOptions createIpsecPolicyOptions = new CreateIpsecPolicyOptions.Builder() .authenticationAlgorithm("sha256") .encryptionAlgorithm("aes256") .pfs("disabled") .name("my-ike-policy") .build(); Response<IPsecPolicy> response = service.createIpsecPolicy(createIpsecPolicyOptions).execute(); IPsecPolicy iPsecPolicy = response.getResult();
const params = { authenticationAlgorithm: 'sha256', encryptionAlgorithm: 'aes256', pfs: 'disabled', name: 'my-ipsec-policy', }; const response = await vpcService.createIpsecPolicy(params);
resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id authentication_algorithm = 'sha256' encryption_algorithm = 'aes256' pfs = 'disabled' key_lifetime = 3600 name = 'my-ipsec-policy' resource_group = resource_group_identity_model response = service.create_ipsec_policy( authentication_algorithm, encryption_algorithm, pfs, key_lifetime=key_lifetime, name=name, resource_group=resource_group, )
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedMust be
disabled
if and only if theencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
disabled
,md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IPsec policy.
The date and time that this IPsec policy was created
The encapsulation mode used. Only
tunnel
is supported.Possible values: [
tunnel
]The encryption algorithm
The
triple_des
algorithm has been deprecatedThe
authentication_algorithm
must bedisabled
if and only ifencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
aes128
,aes128gcm16
,aes192
,aes192gcm16
,aes256
,aes256gcm16
,triple_des
]The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
3600
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ipsec-policy
Perfect Forward Secrecy
Groups
group_2
andgroup_5
have been deprecatedPossible values: [
disabled
,group_14
,group_15
,group_16
,group_17
,group_18
,group_19
,group_2
,group_20
,group_21
,group_22
,group_23
,group_24
,group_31
,group_5
]The resource group for this IPsec policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transform protocol used. Only
esp
is supported.Possible values: [
esp
]
Status Code
The IPsec policy was created successfully.
An invalid IPsec policy prototype object was provided.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:34:16.961597Z", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "key_lifetime": 28800, "name": "my-ipsec-policy-2", "pfs": "disabled", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "ipsec_policy", "transform_protocol": "esp" }
Delete an IPsec policy
This request deletes an IPsec policy. This operation cannot be reversed. For this request to succeed, there must not be any VPN gateway connections using this policy.
DELETE /ipsec_policies/{id}
Request
Path Parameters
The IPsec policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteIpsecPolicyOptions(id) response, err := vpcService.DeleteIpsecPolicy(options)
DeleteIpsecPolicyOptions deleteIpsecPolicyOptions = new DeleteIpsecPolicyOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteIpsecPolicy(deleteIpsecPolicyOptions).execute();
const response = await vpcService.deleteIpsecPolicy({ id });
response = service.delete_ipsec_policy(id)
Retrieve an IPsec policy
This request retrieves a single IPsec policy specified by the identifier in the URL.
GET /ipsec_policies/{id}
Request
Path Parameters
The IPsec policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetIpsecPolicyOptions(id) ipsecPolicy, response, err := vpcService.GetIpsecPolicy(options)
GetIpsecPolicyOptions getIpsecPolicyOptions = new GetIpsecPolicyOptions.Builder() .id(id) .build(); Response<IPsecPolicy> response = service.getIpsecPolicy(getIpsecPolicyOptions).execute(); IPsecPolicy iPsecPolicy = response.getResult();
const response = await vpcService.getIpsecPolicy({ id });
response = service.get_ipsec_policy(id)
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedMust be
disabled
if and only if theencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
disabled
,md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IPsec policy.
The date and time that this IPsec policy was created
The encapsulation mode used. Only
tunnel
is supported.Possible values: [
tunnel
]The encryption algorithm
The
triple_des
algorithm has been deprecatedThe
authentication_algorithm
must bedisabled
if and only ifencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
aes128
,aes128gcm16
,aes192
,aes192gcm16
,aes256
,aes256gcm16
,triple_des
]The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
3600
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ipsec-policy
Perfect Forward Secrecy
Groups
group_2
andgroup_5
have been deprecatedPossible values: [
disabled
,group_14
,group_15
,group_16
,group_17
,group_18
,group_19
,group_2
,group_20
,group_21
,group_22
,group_23
,group_24
,group_31
,group_5
]The resource group for this IPsec policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transform protocol used. Only
esp
is supported.Possible values: [
esp
]
Status Code
The IPsec policy was retrieved successfully.
An IPsec policy with the specified identifier could not be found.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:34:16.961597Z", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "key_lifetime": 28800, "name": "my-ipsec-policy-1", "pfs": "disabled", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "ipsec_policy", "transform_protocol": "esp" }
Update an IPsec policy
This request updates the properties of an existing IPsec policy.
PATCH /ipsec_policies/{id}
Request
Path Parameters
The IPsec policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The IPsec policy patch.
The authentication algorithm
Must be
disabled
if and only if theencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Allowable values: [
disabled
,sha256
,sha384
,sha512
]The encryption algorithm
The
authentication_algorithm
must bedisabled
if and only ifencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Allowable values: [
aes128
,aes128gcm16
,aes192
,aes192gcm16
,aes256
,aes256gcm16
]The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
3600
The name for this IPsec policy. The name must not be used by another IPsec policy in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ipsec-policy
Perfect Forward Secrecy
Allowable values: [
disabled
,group_14
,group_15
,group_16
,group_17
,group_18
,group_19
,group_20
,group_21
,group_22
,group_23
,group_24
,group_31
]
curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-new-ipsec-policy" }'
options := &vpcv1.UpdateIpsecPolicyOptions{ ID: &id, } options.SetEncryptionAlgorithm("aes128") ipsecPolicy, response, err := vpcService.UpdateIpsecPolicy(options)
UpdateIpsecPolicyOptions updateIpsecPolicyOptions = new UpdateIpsecPolicyOptions.Builder() .id(id) .name(name) .build(); Response<IPsecPolicy> response = service.updateIpsecPolicy(updateIpsecPolicyOptions).execute(); IPsecPolicy iPsecPolicy = response.getResult();
const response = await vpcService.updateIpsecPolicy({ id, name: 'my-ipsec-policy', });
authentication_algorithm = 'sha256' encryption_algorithm = 'aes256' key_lifetime = 3600 name = 'ipsec' pfs = 'disabled' response = service.update_ipsec_policy( id, authentication_algorithm=authentication_algorithm, encryption_algorithm=encryption_algorithm, key_lifetime=key_lifetime, name=name, pfs=pfs, )
Response
The authentication algorithm
The
md5
andsha1
algorithms have been deprecatedMust be
disabled
if and only if theencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
disabled
,md5
,sha1
,sha256
,sha384
,sha512
]The VPN gateway connections that use this IPsec policy.
The date and time that this IPsec policy was created
The encapsulation mode used. Only
tunnel
is supported.Possible values: [
tunnel
]The encryption algorithm
The
triple_des
algorithm has been deprecatedThe
authentication_algorithm
must bedisabled
if and only ifencryption_algorithm
isaes128gcm16
,aes192gcm16
, oraes256gcm16
Possible values: [
aes128
,aes128gcm16
,aes192
,aes192gcm16
,aes256
,aes256gcm16
,triple_des
]The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The key lifetime in seconds
Possible values: 1800 ≤ value ≤ 86400
Example:
3600
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-ipsec-policy
Perfect Forward Secrecy
Groups
group_2
andgroup_5
have been deprecatedPossible values: [
disabled
,group_14
,group_15
,group_16
,group_17
,group_18
,group_19
,group_2
,group_20
,group_21
,group_22
,group_23
,group_24
,group_31
,group_5
]The resource group for this IPsec policy
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The transform protocol used. Only
esp
is supported.Possible values: [
esp
]
Status Code
The IPsec policy was updated successfully.
An invalid IPsec policy patch was provided.
An IPsec policy with the specified identifier could not be found.
{ "authentication_algorithm": "sha256", "connections": [], "created_at": "2018-12-13T19:34:16.961597Z", "encapsulation_mode": "tunnel", "encryption_algorithm": "aes256", "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "key_lifetime": 28800, "name": "my-new-ipsec-policy", "pfs": "disabled", "resource_group": { "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771", "id": "3fad3f2204eb4998c3964d254ffcd771", "name": "Default" }, "resource_type": "ipsec_policy", "transform_protocol": "esp" }
List all VPN gateway connections that use a specified IPsec policy
This request lists all VPN gateway connections that use a policy
GET /ipsec_policies/{id}/connections
Request
Path Parameters
The IPsec policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id/connections?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListIpsecPolicyConnectionsOptions{ ID: &id, } response, response, err := vpcService.ListIpsecPolicyConnections(options)
ListIpsecPolicyConnectionsOptions listIpsecPolicyConnectionsOptions = new ListIpsecPolicyConnectionsOptions.Builder() .id(id) .build(); Response<VPNGatewayConnectionCollection> response = service.listIpsecPolicyConnections(listIpsecPolicyConnectionsOptions).execute(); VPNGatewayConnectionCollection vpnGatewayConnectionCollection = response.getResult();
const response = await vpcService.listIpsecPolicyConnections({id});
response = service.list_ipsec_policy_connections(id)
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
Filters the collection to VPN gateways with a
mode
property matching the specified value.Allowable values: [
policy
,route
]Example:
route
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVPNGatewaysOptions{} vpnGateways, response, err := vpcService.ListVPNGateways(options)
ListVpnGatewaysOptions listVpnGatewaysOptions = new ListVpnGatewaysOptions.Builder() .build(); Response<VPNGatewayCollection> response = service.listVpnGateways(listVpnGatewaysOptions).execute(); VPNGatewayCollection vpnGatewayCollection = response.getResult();
const response = await vpcService.listVpnGateways();
response = service.list_vpn_gateways()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
Collection of VPN gateways
vpn_gateways
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The VPN gateways were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways?limit=50" }, "limit": 50, "total_count": 2, "vpn_gateways": [ { "connections": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/bb7baa8f-e4e2-45f5-9286-aac4139d5e78/connections/9736b5a9-0244-475b-a008-ef75a4d72e67", "id": "9736b5a9-0244-475b-a008-ef75a4d72e67", "name": "my-vpn-connection", "resource_type": "vpn_gateway_connection" } ], "created_at": "2018-12-13T19:50:40.740442Z", "crn": "crn:[...]", "health_reasons": [], "health_state": "inapplicable", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/bb7baa8f-e4e2-45f5-9286-aac4139d5e78", "id": "bb7baa8f-e4e2-45f5-9286-aac4139d5e78", "lifecycle_reasons": [], "lifecycle_state": "pending", "members": [ { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-9307477e-0382-4641-81cc-da6f66a47700", "id": "0717-9307477e-0382-4641-81cc-da6f66a47700", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "0.0.0.0", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" } ], "mode": "policy", "name": "my-vpn-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_gateway", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r006-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" } }, { "connections": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc", "id": "b67efb2c-bd17-457d-be8e-7b46404062dc", "name": "my-vpn-connection", "resource_type": "vpn_gateway_connection" } ], "created_at": "2018-12-13T19:38:05.70368Z", "crn": "crn:[...]", "health_reasons": [], "health_state": "inapplicable", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9", "id": "a7d258d5-be1e-491d-83db-526d8d9a2ce9", "lifecycle_reasons": [], "lifecycle_state": "pending", "members": [ { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.1.31", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bb7e061d-7259-45b6-a0da-416ace665269/reserved_ips/0717-dcbdbe8f-8948-4e00-bb6c-17642cb3ad65", "id": "0717-dcbdbe8f-8948-4e00-bb6c-17642cb3ad65", "name": "my-reserved-ip-3", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.1.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bb7e061d-7259-45b6-a0da-416ace665269/reserved_ips/0717-895b4be2-6a4f-4ef9-a75e-793d5e0de717", "id": "0717-895b4be2-6a4f-4ef9-a75e-793d5e0de717", "name": "my-reserved-ip-4", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "0.0.0.0", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" } ], "mode": "policy", "name": "my-vpn-gateway-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_gateway", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r006-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" } } ] }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN gateway prototype object.
Identifies a subnet by a unique property.
The name for this VPN gateway. The name must not be used by another VPN gateway in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-gateway
The resource group to use. If unspecified, the account's default resource group will be used.
Route mode VPN gateway
Allowable values: [
route
]Default:
route
One of
curl -X POST "$vpc_api_endpoint/v1/vpn_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-new-vpn-gateway", "mode": "policy", "subnet": { "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401" }, "resource_group": { "id": "56969d60-43e9-465c-883c-b9f7363e78e8" } }'
options := &vpcv1.CreateVPNGatewayOptions{} options.SetName(name) options.SetSubnet(&vpcv1.SubnetIdentity{ ID: &subnetId, }) vpnGateway, response, err := vpcService.CreateVPNGateway(options)
SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); CreateVpnGatewayOptions createVpnGatewayOptions = new CreateVpnGatewayOptions.Builder() .subnet(subnetIdentityModel) .name("my-vpn-gateway") .build(); Response<VPNGateway> response = service.createVpnGateway(createVpnGatewayOptions).execute(); VPNGateway vpnGateway = response.getResult();
const subnetIdentityModel = { id: subnetID, }; const params = { name: 'my-vpn-gateway', subnet: subnetIdentityModel, }; const response = await vpcService.createVpnGateway(params);
subnet_identity_model = {} subnet_identity_model['id'] = subnet_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id subnet = subnet_identity_model name = 'my-vpn-gateway' resource_group = resource_group_identity_model response = service.create_vpn_gateway( subnet, name=name, resource_group=resource_group, )
Response
Connections for this VPN gateway.
The date and time that this VPN gateway was created
The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
Collection of VPN gateway members
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource group for this VPN gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
- Examples:View
The VPC this VPN gateway resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Route mode VPN gateway
Possible values: [
route
]
One of
Status Code
The VPN gateway was created successfully.
An invalid VPN gateway prototype object was provided.
{ "connections": [], "created_at": "2018-12-13T17:29:36.921569Z", "crn": "crn:[...]", "health_reasons": [], "health_state": "inapplicable", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/e630bb38-c3a7-4619-b0e5-7bff14e060fe", "id": "e630bb38-c3a7-4619-b0e5-7bff14e060fe", "lifecycle_reasons": [], "lifecycle_state": "pending", "members": [ { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-9307477e-0382-4641-81cc-da6f66a47700", "id": "0717-9307477e-0382-4641-81cc-da6f66a47700", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "0.0.0.0", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" } ], "mode": "policy", "name": "my-new-vpn-gateway", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_gateway", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r006-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" } }
Delete a VPN gateway
This request deletes a VPN gateway. This operation cannot be reversed. For this request to
succeed, the VPN gateway must not have a status
of pending
, and there must not be any
VPC routes using the VPN gateway's connections as a next hop.
DELETE /vpn_gateways/{id}
Request
Path Parameters
The VPN gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteVPNGatewayOptions(id) response, err := vpcService.DeleteVPNGateway(options)
DeleteVpnGatewayOptions deleteVpnGatewayOptions = new DeleteVpnGatewayOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteVpnGateway(deleteVpnGatewayOptions).execute();
const response = await vpcService.deleteVpnGateway({ id });
response = service.delete_vpn_gateway(id)
Retrieve a VPN gateway
This request retrieves a single VPN gateway specified by the identifier in the URL.
GET /vpn_gateways/{id}
Request
Path Parameters
The VPN gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetVPNGatewayOptions(id) vpnGateway, response, err := vpcService.GetVPNGateway(options)
GetVpnGatewayOptions getVpnGatewayOptions = new GetVpnGatewayOptions.Builder() .id(id) .build(); Response<VPNGateway> response = service.getVpnGateway(getVpnGatewayOptions).execute(); VPNGateway vpnGateway = response.getResult();
const response = await vpcService.getVpnGateway({ id });
response = service.get_vpn_gateway(id)
Response
Connections for this VPN gateway.
The date and time that this VPN gateway was created
The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
Collection of VPN gateway members
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource group for this VPN gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
- Examples:View
The VPC this VPN gateway resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Route mode VPN gateway
Possible values: [
route
]
One of
Status Code
The VPN gateway was retrieved successfully.
A VPN gateway with the specified identifier could not be found.
{ "connections": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc", "id": "b67efb2c-bd17-457d-be8e-7b46404062dc", "name": "my-vpn-connection", "resource_type": "vpn_gateway_connection" } ], "created_at": "2018-12-13T19:38:05.70368Z", "crn": "crn:[...]", "health_reasons": [], "health_state": "inapplicable", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9", "id": "a7d258d5-be1e-491d-83db-526d8d9a2ce9", "lifecycle_reasons": [], "lifecycle_state": "pending", "members": [ { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-9307477e-0382-4641-81cc-da6f66a47700", "id": "0717-9307477e-0382-4641-81cc-da6f66a47700", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "0.0.0.0", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" } ], "mode": "policy", "name": "my-vpn-gateway-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_gateway", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r006-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" } }
Update a VPN gateway
This request updates the properties of an existing VPN gateway.
PATCH /vpn_gateways/{id}
Request
Path Parameters
The VPN gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN gateway patch.
The name for this VPN gateway. The name must not be used by another VPN gateway in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-gateway
curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpn-gateway-1" }'
options := &vpcv1.UpdateVPNGatewayOptions{ ID: &id, Name: &name, } vpnGateway, response, err := vpcService.UpdateVPNGateway(options)
UpdateVpnGatewayOptions updateVpnGatewayOptions = new UpdateVpnGatewayOptions.Builder() .id(id) .name(name) .build(); Response<VPNGateway> response = service.updateVpnGateway(updateVpnGatewayOptions).execute(); VPNGateway vpnGateway = response.getResult();
const response = await vpcService.updateVpnGateway({ id, name: 'my-vpn-gateway' });
response = service.update_vpn_gateway( id, name='my-vpn-gateway', )
Response
Connections for this VPN gateway.
The date and time that this VPN gateway was created
The VPN gateway's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn:ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The VPN gateway's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this VPN gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
Collection of VPN gateway members
The name for this VPN gateway. The name is unique across all VPN gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-gateway
The resource group for this VPN gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
- Examples:View
The VPC this VPN gateway resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Route mode VPN gateway
Possible values: [
route
]
One of
Status Code
The VPN gateway was updated successfully.
An invalid VPN gateway patch was provided.
The VPN gateway is not allowed to be updated.
A VPN gateway with the specified identifier could not be found.
{ "connections": [], "created_at": "2018-12-13T17:29:36.921569Z", "crn": "crn:[...]", "health_reasons": [], "health_state": "inapplicable", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/e630bb38-c3a7-4619-b0e5-7bff14e060fe", "id": "e630bb38-c3a7-4619-b0e5-7bff14e060fe", "lifecycle_reasons": [], "lifecycle_state": "pending", "members": [ { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-9307477e-0382-4641-81cc-da6f66a47700", "id": "0717-9307477e-0382-4641-81cc-da6f66a47700", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "0.0.0.0", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "active" }, { "health_reasons": [], "health_state": "inapplicable", "lifecycle_reasons": [], "lifecycle_state": "pending", "private_ip": { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "public_ip": { "address": "0.0.0.0" }, "role": "standby" } ], "mode": "policy", "name": "my-vpn-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_gateway", "subnet": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r006-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" } }
List all connections of a VPN gateway
This request lists all connections of a VPN gateway.
GET /vpn_gateways/{vpn_gateway_id}/connections
Request
Path Parameters
The VPN gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to VPN gateway connections with a
status
property matching the specified value.Allowable values: [
down
,up
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVPNGatewayConnectionsOptions{} options.SetVPNGatewayID(gatewayID) vpnGatewayConnections, response, err := vpcService.ListVPNGatewayConnections( options )
ListVpnGatewayConnectionsOptions listVpnGatewayConnectionsOptions = new ListVpnGatewayConnectionsOptions.Builder() .vpnGatewayId(vpnGatewayId) .build(); Response<VPNGatewayConnectionCollection> response = service.listVpnGatewayConnections(listVpnGatewayConnectionsOptions).execute(); VPNGatewayConnectionCollection vpnGatewayConnectionCollection = response.getResult();
const response = await vpcService.listVpnGatewayConnections({ vpnGatewayId });
response = service.list_vpn_gateway_connections(vpn_gateway_id)
Response
Collection of VPN gateway connections in a VPN gateway
Array of VPN gateway connections
connections
Status Code
The VPN gateway connections were retrieved successfully.
A VPN gateway with the specified identifier could not be found.
{ "connections": [ { "admin_state_up": true, "authentication_mode": "psk", "created_at": "2018-12-13T19:40:12.124082Z", "dead_peer_detection": { "action": "none", "interval": 15, "timeout": 30 }, "establish_mode": "peer_only", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "local": { "cidrs": [ "192.0.2.0/24" ], "ike_identities": [ { "type": "ipv4_address", "value": "192.0.2.4" } ] }, "mode": "policy", "name": "my-vpn-connection-1", "peer": { "address": "192.0.2.5", "cidrs": [ "192.0.3.0/24" ], "ike_identity": { "type": "ipv4_address", "value": "192.0.2.5" }, "type": "address" }, "psk": "lkj14b1oi0alcniejkso", "resource_type": "vpn_gateway_connection", "status": "down", "status_reasons": [] }, { "admin_state_up": true, "authentication_mode": "psk", "created_at": "2018-12-13T19:39:47.938464Z", "dead_peer_detection": { "action": "none", "interval": 15, "timeout": 30 }, "establish_mode": "bidirectional", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc", "id": "b67efb2c-bd17-457d-be8e-7b46404062dc", "ike_policy": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d", "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d", "name": "my-ike-policy", "resource_type": "ike_policy" }, "ipsec_policy": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "name": "my-ipsec-policy", "resource_type": "ipsec_policy" }, "local": { "cidrs": [ "192.0.2.0/24" ], "ike_identities": [ { "type": "ipv4_address", "value": "192.0.2.4" } ] }, "mode": "policy", "name": "my-vpn-connection-2", "peer": { "address": "192.0.2.5", "cidrs": [ "192.0.3.0/24" ], "ike_identity": { "type": "ipv4_address", "value": "192.0.2.5" }, "type": "address" }, "psk": "lkj14b1oi0alcniejkso", "resource_type": "vpn_gateway_connection", "status": "down", "status_reasons": [] } ] }
Create a connection for a VPN gateway
This request creates a new VPN gateway connection.
POST /vpn_gateways/{vpn_gateway_id}/connections
Request
Path Parameters
The VPN gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN gateway connection prototype object.
The pre-shared key
Possible values: Value must match regular expression
^(?=[\-\+\&\!\@\#\$\%\^\*\(\)\,\.\:\_a-zA-Z0-9]{6,128}$)(?:(?!^0[xs]).).*$
Example:
lkj14b1oi0alcniejkso
If set to false, the VPN gateway connection is shut down
Default:
true
The Dead Peer Detection settings.
The establish mode of the VPN gateway connection:
bidirectional
: Either side of the VPN gateway can initiate IKE protocol negotiations or rekeying processes.peer_only
: Only the peer can initiate IKE protocol negotiations for this VPN gateway connection. Additionally, the peer is responsible for initiating the rekeying process after the connection is established. If rekeying does not occur, the VPN gateway connection will be brought down after its lifetime expires.
Allowable values: [
bidirectional
,peer_only
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
bidirectional
Example:
bidirectional
The IKE policy to use. If unspecified, auto-negotiation will be used
The IPsec policy to use. If unspecified, auto-negotiation will be used
The name for this VPN gateway connection. The name must not be used by another connection for the VPN gateway. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-connection
Routing protocols are disabled for this VPN gateway connection.
Allowable values: [
none
]Default:
none
One of
curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "admin_state_up": true, "dead_peer_detection": { "interval": 15, "timeout": 30 }, "local": { "cidrs": ["192.0.2.50/24"] }, "ike_policy": { "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d" }, "ipsec_policy": { "id": "43c2f663-3960-4289-9253-f6eab23a6cd7" }, "name": "my-vpn-connection-2", "peer": { "cidrs": ["192.0.2.40/24"], "address": "192.0.2.5" }, "psk": "lkj14b1oi0alcniejkso" }'
options := &vpcv1.CreateVPNGatewayConnectionOptions{ VPNGatewayID: &gatewayID, } vpnGatewayConnectionPrototype := &vpcv1.VPNGatewayConnectionPrototype{ Name: &name, Peer: &vpcv1.VPNGatewayConnectionStaticRouteModePeerPrototype{ Address: &peerAddress, }, Psk: core.StringPtr("lkj14b1oi0alcniejkso"), } options.SetVPNGatewayConnectionPrototype(vpnGatewayConnectionPrototype) vpnGatewayConnection, response, err := vpcService.CreateVPNGatewayConnection( options, )
VPNGatewayConnectionStaticRouteModePeerPrototypeVPNGatewayConnectionPeerByAddress vpnGatewayConnectionStaticRouteModePeerPrototypeModel = new VPNGatewayConnectionStaticRouteModePeerPrototypeVPNGatewayConnectionPeerByAddress.Builder() .address("169.21.50.5") .build(); VPNGatewayConnectionPrototypeVPNGatewayConnectionStaticRouteModePrototype vpnGatewayConnectionPrototypeModel = new VPNGatewayConnectionPrototypeVPNGatewayConnectionStaticRouteModePrototype.Builder() .name("my-vpn-connection") .psk("lkj14b1oi0alcniejkso") .peer(vpnGatewayConnectionStaticRouteModePeerPrototypeModel) .build(); CreateVpnGatewayConnectionOptions createVpnGatewayConnectionOptions = new CreateVpnGatewayConnectionOptions.Builder() .vpnGatewayId(vpnGatewayId) .vpnGatewayConnectionPrototype(vpnGatewayConnectionPrototypeModel) .build(); Response<VPNGatewayConnection> response = vpcService.createVpnGatewayConnection(createVpnGatewayConnectionOptions).execute(); VPNGatewayConnection vpnGatewayConnection = response.getResult();
const vpnGatewayConnectionStaticRouteModePeerPrototypeModel = { address: '169.21.50.5', }; const vpnGatewayConnectionPrototypeModel = { name: 'my-vpn-connection', psk: 'lkj14b1oi0alcniejkso', peer: vpnGatewayConnectionStaticRouteModePeerPrototypeModel, }; const params = { vpnGatewayId: vpnGatewayId, vpnGatewayConnectionPrototype: vpnGatewayConnectionPrototypeModel, }; const response = await vpcService.createVpnGatewayConnection(params);
vpn_gateway_connection_dpd_prototype_model = {} vpn_gateway_connection_dpd_prototype_model['action'] = 'restart' vpn_gateway_connection_dpd_prototype_model['interval'] = 30 vpn_gateway_connection_dpd_prototype_model['timeout'] = 120 ike_policy_identity_model = {} ike_policy_identity_model['id'] = ike_policy_id i_psec_policy_identity_model = {} i_psec_policy_identity_model['id'] = ipsec_policy_id dead_peer_detection = vpn_gateway_connection_dpd_prototype_model ike_policy = ike_policy_identity_model ipsec_policy = i_psec_policy_identity_model peer_address = '169.21.50.5' psk = 'my-password' admin_state_up = True name = 'my-vpn-connection' vpn_gateway_connection_static_route_mode_peer_prototype_model = { 'address': peer_address, } vpn_gateway_connection_prototype_model = { 'psk': psk, 'peer': vpn_gateway_connection_static_route_mode_peer_prototype_model, 'name': name, 'admin_state_up': admin_state_up, 'dead_peer_detection'=dead_peer_detection, 'ike_policy'=ike_policy, 'ipsec_policy'=ipsec_policy, } response = vpc_service.create_vpn_gateway_connection( vpn_gateway_id=vpn_gateway_id, vpn_gateway_connection_prototype=vpn_gateway_connection_prototype_model, ) vpn_gateway_connection = response.get_result()
Response
If set to false, the VPN gateway connection is shut down
The authentication mode. Only
psk
is currently supported.Possible values: [
psk
]The date and time that this VPN gateway connection was created
The Dead Peer Detection settings.
The establish mode of the VPN gateway connection:
bidirectional
: Either side of the VPN gateway can initiate IKE protocol negotiations or rekeying processes.peer_only
: Only the peer can initiate IKE protocol negotiations for this VPN gateway connection. Additionally, the peer is responsible for initiating the rekeying process after the connection is established. If rekeying does not occur, the VPN gateway connection will be brought down after its lifetime expires.
Possible values: [
bidirectional
,peer_only
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
bidirectional
The VPN connection's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b/connections/93487806-7743-4c46-81d6-72869883ea0b
The unique identifier for this VPN gateway connection
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a10a5771-dc23-442c-8460-c3601d8542f7
The mode of the VPN gateway
Possible values: [
policy
,route
]Example:
route
The name for this VPN gateway connection. The name is unique across all connections for the VPN gateway.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-connection
The pre-shared key
Possible values: Value must match regular expression
^(?=[\-\+\&\!\@\#\$\%\^\*\(\)\,\.\:\_a-zA-Z0-9]{6,128}$)(?:(?!^0[xs]).).*$
Example:
lkj14b1oi0alcniejkso
The resource type
Possible values: [
vpn_gateway_connection
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of a VPN gateway connection
Possible values: [
down
,up
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current VPN gateway connection status (if any).
Possible values: number of items ≥ 0
The IKE policy. If absent, auto-negotiation is used
The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ike-policy
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ike_policy
The IPsec policy. If absent, auto-negotiation is used
The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ipsec-policy
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ipsec_policy
One of
Status Code
The VPN gateway connection was created successfully.
An invalid VPN gateway connection prototype object was provided.
The VPN gateway connection is not allowed to be created.
{ "admin_state_up": true, "authentication_mode": "psk", "created_at": "2018-12-13T19:39:47.938464Z", "dead_peer_detection": { "action": "none", "interval": 15, "timeout": 30 }, "establish_mode": "bidirectional", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc", "id": "b67efb2c-bd17-457d-be8e-7b46404062dc", "ike_policy": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d", "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d", "name": "my-ike-policy", "resource_type": "ike_policy" }, "ipsec_policy": { "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7", "id": "43c2f663-3960-4289-9253-f6eab23a6cd7", "name": "my-ipsec-policy", "resource_type": "ipsec_policy" }, "local": { "cidrs": [ "192.0.2.0/24" ], "ike_identities": [ { "type": "ipv4_address", "value": "192.0.2.4" } ] }, "mode": "policy", "name": "my-vpn-connection-2", "peer": { "address": "192.0.2.5", "cidrs": [ "192.0.3.0/24" ], "ike_identity": { "type": "ipv4_address", "value": "192.0.2.5" }, "type": "address" }, "psk": "lkj14b1oi0alcniejkso", "resource_type": "vpn_gateway_connection", "status": "down", "status_reasons": [] }
Delete a VPN gateway connection
This request deletes a VPN gateway connection. This operation cannot be reversed. For this request to succeed, there must not be VPC routes using this VPN connection as a next hop.
DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteVPNGatewayConnectionOptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) response, err := vpcService.DeleteVPNGatewayConnection(options)
DeleteVpnGatewayConnectionOptions deleteVpnGatewayConnectionOptions = new DeleteVpnGatewayConnectionOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .build(); Response<Void> response = service.deleteVpnGatewayConnection(deleteVpnGatewayConnectionOptions).execute();
const response = await vpcService.deleteVpnGatewayConnection({ vpnGatewayId, id, });
response = service.delete_vpn_gateway_connection(vpn_gateway_id, id)
Retrieve a VPN gateway connection
This request retrieves a single VPN gateway connection specified by the identifier in the URL.
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetVPNGatewayConnectionOptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) vpnGatewayConnection, response, err := vpcService.GetVPNGatewayConnection(options)
GetVpnGatewayConnectionOptions getVpnGatewayConnectionOptions = new GetVpnGatewayConnectionOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .build(); Response<VPNGatewayConnection> response = service.getVpnGatewayConnection(getVpnGatewayConnectionOptions).execute(); VPNGatewayConnection vpnGatewayConnection = response.getResult();
const response = await vpcService.getVpnGatewayConnection({ vpnGatewayId, id });
response = service.get_vpn_gateway_connection(vpn_gateway_id, id)
Response
If set to false, the VPN gateway connection is shut down
The authentication mode. Only
psk
is currently supported.Possible values: [
psk
]The date and time that this VPN gateway connection was created
The Dead Peer Detection settings.
The establish mode of the VPN gateway connection:
bidirectional
: Either side of the VPN gateway can initiate IKE protocol negotiations or rekeying processes.peer_only
: Only the peer can initiate IKE protocol negotiations for this VPN gateway connection. Additionally, the peer is responsible for initiating the rekeying process after the connection is established. If rekeying does not occur, the VPN gateway connection will be brought down after its lifetime expires.
Possible values: [
bidirectional
,peer_only
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
bidirectional
The VPN connection's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b/connections/93487806-7743-4c46-81d6-72869883ea0b
The unique identifier for this VPN gateway connection
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a10a5771-dc23-442c-8460-c3601d8542f7
The mode of the VPN gateway
Possible values: [
policy
,route
]Example:
route
The name for this VPN gateway connection. The name is unique across all connections for the VPN gateway.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-connection
The pre-shared key
Possible values: Value must match regular expression
^(?=[\-\+\&\!\@\#\$\%\^\*\(\)\,\.\:\_a-zA-Z0-9]{6,128}$)(?:(?!^0[xs]).).*$
Example:
lkj14b1oi0alcniejkso
The resource type
Possible values: [
vpn_gateway_connection
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of a VPN gateway connection
Possible values: [
down
,up
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current VPN gateway connection status (if any).
Possible values: number of items ≥ 0
The IKE policy. If absent, auto-negotiation is used
The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ike-policy
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ike_policy
The IPsec policy. If absent, auto-negotiation is used
The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ipsec-policy
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ipsec_policy
One of
Status Code
The VPN gateway connection was retrieved successfully.
A VPN gateway connection with the specified identifier could not be found.
{ "admin_state_up": true, "authentication_mode": "psk", "created_at": "2018-12-13T19:40:12.124082Z", "dead_peer_detection": { "action": "none", "interval": 15, "timeout": 30 }, "establish_mode": "bidirectional", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "local": { "cidrs": [ "192.0.2.0/24" ], "ike_identities": [ { "type": "ipv4_address", "value": "192.0.2.4" } ] }, "mode": "policy", "name": "my-vpn-connection-1", "peer": { "address": "192.0.2.5", "cidrs": [ "192.0.3.0/24" ], "ike_identity": { "type": "ipv4_address", "value": "192.0.2.5" }, "type": "address" }, "psk": "lkj14b1oi0alcniejkso", "resource_type": "vpn_gateway_connection", "status": "down", "status_reasons": [] }
Update a VPN gateway connection
This request updates the properties of an existing VPN gateway connection.
PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN gateway connection patch.
If set to false, the VPN gateway connection is shut down
The Dead Peer Detection settings.
The establish mode of the VPN gateway connection:
bidirectional
: Either side of the VPN gateway can initiate IKE protocol negotiations or rekeying processes.peer_only
: Only the peer can initiate IKE protocol negotiations for this VPN gateway connection. Additionally, the peer is responsible for initiating the rekeying process after the connection is established. If rekeying does not occur, the VPN gateway connection will be brought down after its lifetime expires.
Allowable values: [
bidirectional
,peer_only
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
bidirectional
The IKE policy to use. Specify
null
to remove any existing policy, resulting in auto-negotiationThe IPsec policy to use. Specify
null
to remove any existing policy, resulting in auto-negotiationThe name for this VPN gateway connection. The name must not be used by another connection for the VPN gateway.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-connection
The pre-shared key
Possible values: Value must match regular expression
^(?=[\-\+\&\!\@\#\$\%\^\*\(\)\,\.\:\_a-zA-Z0-9]{6,128}$)(?:(?!^0[xs]).).*$
Example:
lkj14b1oi0alcniejkso
Routing protocols are disabled for this VPN gateway connection.
Allowable values: [
none
]
curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpn-connection-1"}'
options := &vpcv1.UpdateVPNGatewayConnectionOptions{ ID: &connID, VpnGatewayID: &gatewayID, Name: &name, } vpnGatewayConnection, response, err := vpcService.UpdateVPNGatewayConnection( options )
UpdateVpnGatewayConnectionOptions updateVpnGatewayConnectionOptions = new UpdateVpnGatewayConnectionOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .name(name) .build(); Response<VPNGatewayConnection> response = service.updateVpnGatewayConnection(updateVpnGatewayConnectionOptions).execute(); VPNGatewayConnection vpnGatewayConnection = response.getResult();
const params = { vpnGatewayId, id, name: 'my-vpn-gateway-connection', }; const response = await vpcService.updateVpnGatewayConnection(params);
vpn_gateway_connection_dpd_prototype_model = {} vpn_gateway_connection_dpd_prototype_model['action'] = 'restart' vpn_gateway_connection_dpd_prototype_model['interval'] = 30 vpn_gateway_connection_dpd_prototype_model['timeout'] = 120 ike_policy_identity_model = {} ike_policy_identity_model['id'] = ike_policy_id i_psec_policy_identity_model = {} i_psec_policy_identity_model['id'] = ipsec_policy_id admin_state_up = True dead_peer_detection = vpn_gateway_connection_dpd_prototype_model ike_policy = ike_policy_identity_model ipsec_policy = i_psec_policy_identity_model name = 'my-vpn-connection' peer_address = '169.21.50.5' psk = 'lkj14b1oi0alcniejkso' response = service.update_vpn_gateway_connection( vpn_gateway_id, id, admin_state_up=admin_state_up, dead_peer_detection=dead_peer_detection, ike_policy=ike_policy, ipsec_policy=ipsec_policy, name=name, peer_address=peer_address, psk=psk, )
Response
If set to false, the VPN gateway connection is shut down
The authentication mode. Only
psk
is currently supported.Possible values: [
psk
]The date and time that this VPN gateway connection was created
The Dead Peer Detection settings.
The establish mode of the VPN gateway connection:
bidirectional
: Either side of the VPN gateway can initiate IKE protocol negotiations or rekeying processes.peer_only
: Only the peer can initiate IKE protocol negotiations for this VPN gateway connection. Additionally, the peer is responsible for initiating the rekeying process after the connection is established. If rekeying does not occur, the VPN gateway connection will be brought down after its lifetime expires.
Possible values: [
bidirectional
,peer_only
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
bidirectional
The VPN connection's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/ddf51bec-3424-11e8-b467-0ed5f89f718b/connections/93487806-7743-4c46-81d6-72869883ea0b
The unique identifier for this VPN gateway connection
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
a10a5771-dc23-442c-8460-c3601d8542f7
The mode of the VPN gateway
Possible values: [
policy
,route
]Example:
route
The name for this VPN gateway connection. The name is unique across all connections for the VPN gateway.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-connection
The pre-shared key
Possible values: Value must match regular expression
^(?=[\-\+\&\!\@\#\$\%\^\*\(\)\,\.\:\_a-zA-Z0-9]{6,128}$)(?:(?!^0[xs]).).*$
Example:
lkj14b1oi0alcniejkso
The resource type
Possible values: [
vpn_gateway_connection
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of a VPN gateway connection
Possible values: [
down
,up
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current VPN gateway connection status (if any).
Possible values: number of items ≥ 0
The IKE policy. If absent, auto-negotiation is used
The IKE policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ike_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IKE policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IKE policy. The name is unique across all IKE policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ike-policy
The resource type
Possible values: [
ike_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ike_policy
The IPsec policy. If absent, auto-negotiation is used
The IPsec policy's canonical URL
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/ddf51bec-3424-11e8-b467-0ed5f89f718b
The unique identifier for this IPsec policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
ddf51bec-3424-11e8-b467-0ed5f89f718b
The name for this IPsec policy. The name is unique across all IPsec policies in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-ipsec-policy
The resource type
Possible values: [
ipsec_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
ipsec_policy
One of
Status Code
The VPN gateway connection was updated successfully.
An invalid VPN gateway connection patch was provided.
The VPN gateway connection is not allowed to be updated.
A VPN gateway connection with the specified identifier could not be found.
{ "admin_state_up": true, "authentication_mode": "psk", "created_at": "2018-12-13T19:40:12.124082Z", "dead_peer_detection": { "action": "none", "interval": 15, "timeout": 30 }, "establish_mode": "bidirectional", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c", "local": { "cidrs": [ "192.0.2.0/24" ], "ike_identities": [ { "type": "ipv4_address", "value": "192.0.2.4" } ] }, "mode": "policy", "name": "my-vpn-connection-1", "peer": { "address": "192.0.2.5", "cidrs": [ "192.0.3.0/24" ], "ike_identity": { "type": "ipv4_address", "value": "192.0.2.5" }, "type": "address" }, "psk": "lkj14b1oi0alcniejkso", "resource_type": "vpn_gateway_connection", "status": "down", "status_reasons": [] }
List all local CIDRs for a VPN gateway connection
This request lists all local CIDRs for a VPN gateway connection.
This request is only supported for policy mode VPN gateways.
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/local/cidrs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVPNGatewayConnectionsLocalCidrsOptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) localCIDRs, response, err := vpcService.ListVPNGatewayConnectionsLocalCidrs(options)
ListVpnGatewayConnectionsLocalCidrsOptions listVpnGatewayConnectionsLocalCidrsOptions = new ListVpnGatewayConnectionsLocalCidrsOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .build(); Response<VPNGatewayConnectionCIDRs> response = service.listVpnGatewayConnectionsLocalCidrs(listVpnGatewayConnectionsLocalCidrsOptions).execute(); VPNGatewayConnectionCIDRs vpnGatewayConnectionCidRs = response.getResult();
const response = await vpcService.listVpnGatewayConnectionsLocalCidrs({ vpnGatewayId, id, });
response = service.list_vpn_gateway_connections_local_cidrs( vpn_gateway_id, id)
Response
The CIDRs for this resource.
Possible values: number of items ≥ 1, 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Status Code
The CIDRs were retrieved successfully.
A VPN gateway connection with the specified identifier could not be found.
{ "cidrs": [ "0.0.19.0/24" ] }
Remove a local CIDR from a VPN gateway connection
This request removes a CIDR from a VPN gateway connection.
This request is only supported for policy mode VPN gateways.
DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/local/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.RemoveVPNGatewayConnectionsLocalCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.RemoveVPNGatewayConnectionsLocalCIDR(options)
RemoveVpnGatewayConnectionsLocalCidrOptions removeVpnGatewayConnectionsLocalCidrOptions = new RemoveVpnGatewayConnectionsLocalCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.removeVpnGatewayConnectionsLocalCidr(removeVpnGatewayConnectionsLocalCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.removeVpnGatewayConnectionsLocalCidr(params);
response = service.remove_vpn_gateway_connections_local_cidr( vpn_gateway_id, id, cidr)
Response
Status Code
The CIDR was successfully removed from the specified VPN gateway connection.
The last CIDR could not be removed from the specified VPN gateway connection.
The CIDR is not allowed to be removed from the specified VPN gateway connection.
The specified CIDR does not exist on the specified VPN gateway connection or the specified VPN gateway connection could not be found.
No Sample Response
Check if the specified local CIDR exists on a VPN gateway connection
This request succeeds if a CIDR exists on the specified VPN gateway connection, and fails otherwise.
This request is only supported for policy mode VPN gateways.
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/local/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.CheckVPNGatewayConnectionsLocalCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.CheckVPNGatewayConnectionsLocalCIDR(options)
CheckVpnGatewayConnectionsLocalCidrOptions checkVpnGatewayConnectionsLocalCidrOptions = new CheckVpnGatewayConnectionsLocalCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.checkVpnGatewayConnectionsLocalCidr(checkVpnGatewayConnectionsLocalCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.checkVpnGatewayConnectionsLocalCidr(params);
response = service.check_vpn_gateway_connections_local_cidr( vpn_gateway_id, id, cidr)
Set a local CIDR on a VPN gateway connection
This request adds the specified CIDR to the specified VPN gateway connection. This request succeeds if the specified CIDR already exists. A request body is not required, and if provided, is ignored.
This request is only supported for policy mode VPN gateways.
PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/local/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/local/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.AddVPNGatewayConnectionsLocalCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.AddVPNGatewayConnectionsLocalCIDR(options)
AddVpnGatewayConnectionsLocalCidrOptions addVpnGatewayConnectionsLocalCidrOptions = new AddVpnGatewayConnectionsLocalCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.addVpnGatewayConnectionsLocalCidr(addVpnGatewayConnectionsLocalCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.addVpnGatewayConnectionsLocalCidr(params);
response = service.add_vpn_gateway_connections_local_cidr( vpn_gateway_id, id, cidr)
Response
Status Code
The CIDR was successfully set on the specified VPN gateway connection.
The CIDR is already set on the specified VPN gateway connection.
The specified CIDR was invalid.
The CIDR is not allowed to be set on the specified VPN gateway connection.
The specified VPN gateway connection could not be found.
No Sample Response
List all peer CIDRs for a VPN gateway connection
This request lists all peer CIDRs for a VPN gateway connection.
This request is only supported for policy mode VPN gateways.
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/peer/cidrs?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListVPNGatewayConnectionsPeerCidrsOptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) peerCIDRs, response, err := vpcService.ListVPNGatewayConnectionsPeerCidrs(options)
ListVpnGatewayConnectionsPeerCidrsOptions listVpnGatewayConnectionsPeerCidrsOptions = new ListVpnGatewayConnectionsPeerCidrsOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .build(); Response<VPNGatewayConnectionCIDRs> response = service.listVpnGatewayConnectionsPeerCidrs(listVpnGatewayConnectionsPeerCidrsOptions).execute(); VPNGatewayConnectionCIDRs vpnGatewayConnectionCidRs = response.getResult();
const response = await vpcService.listVpnGatewayConnectionsPeerCidrs({ id, vpnGatewayId, });
response = service.list_vpn_gateway_connections_peer_cidrs( vpn_gateway_id, id)
Response
The CIDRs for this resource.
Possible values: number of items ≥ 1, 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Status Code
The CIDRs were retrieved successfully.
A VPN gateway connection with the specified identifier could not be found.
{ "cidrs": [ "0.0.150.0/24" ] }
Remove a peer CIDR from a VPN gateway connection
This request removes a CIDR from a VPN gateway connection.
This request is only supported for policy mode VPN gateways.
DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/peer/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.RemoveVPNGatewayConnectionsPeerCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.RemoveVPNGatewayConnectionsPeerCIDR(options)
RemoveVpnGatewayConnectionsPeerCidrOptions removeVpnGatewayConnectionsPeerCidrOptions = new RemoveVpnGatewayConnectionsPeerCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.removeVpnGatewayConnectionsPeerCidr(removeVpnGatewayConnectionsPeerCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.removeVpnGatewayConnectionsPeerCidr(params);
response = service.remove_vpn_gateway_connections_peer_cidr( vpn_gateway_id, id, cidr)
Response
Status Code
The CIDR was successfully removed from the specified VPN gateway connection.
The last CIDR could not be removed from the specified VPN gateway connection.
The CIDR is not allowed to be removed from the specified VPN gateway connection.
The specified CIDR does not exist on the specified VPN gateway connection or the specified VPN gateway connection could not be found.
No Sample Response
Check if the specified peer CIDR exists on a VPN gateway connection
This request succeeds if a CIDR exists on the specified VPN gateway connection, and fails otherwise.
This request is only supported for policy mode VPN gateways.
GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/peer/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.CheckVPNGatewayConnectionsPeerCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.CheckVPNGatewayConnectionsPeerCIDR(options)
CheckVpnGatewayConnectionsPeerCidrOptions checkVpnGatewayConnectionsPeerCidrOptions = new CheckVpnGatewayConnectionsPeerCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.checkVpnGatewayConnectionsPeerCidr(checkVpnGatewayConnectionsPeerCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.checkVpnGatewayConnectionsPeerCidr(params);
response = service.check_vpn_gateway_connections_peer_cidr( vpn_gateway_id, id, cidr)
Set a peer CIDR on a VPN gateway connection
This request adds the specified CIDR to the specified VPN gateway connection. This request succeeds if the specified CIDR already exists. A request body is not required, and if provided, is ignored.
This request is only supported for policy mode VPN gateways.
PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer/cidrs/{cidr}
Request
Path Parameters
The VPN gateway identifier
The VPN gateway connection identifier
The IP address range in CIDR block notation.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.1.0/24
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/peer/cidrs/$cidr?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.AddVPNGatewayConnectionsPeerCIDROptions{} options.SetVPNGatewayID(gatewayID) options.SetID(connID) options.SetCIDR(CIDR) response, err := vpcService.AddVPNGatewayConnectionsPeerCIDR(options)
AddVpnGatewayConnectionsPeerCidrOptions addVpnGatewayConnectionsPeerCidrOptions = new AddVpnGatewayConnectionsPeerCidrOptions.Builder() .vpnGatewayId(vpnGatewayId) .id(id) .cidr(cidr) .build(); Response<Void> response = service.addVpnGatewayConnectionsPeerCidr(addVpnGatewayConnectionsPeerCidrOptions).execute();
const params = { vpnGatewayId, id, cidr, }; const response = await vpcService.addVpnGatewayConnectionsPeerCidr(params);
response = service.add_vpn_gateway_connections_peer_cidr( vpn_gateway_id, id, cidr)
Response
Status Code
The CIDR was successfully set on the specified VPN gateway connection.
The CIDR is already set on the specified VPN gateway connection.
The specified CIDR was invalid.
The CIDR is not allowed to be set on the specified VPN gateway connection.
The specified VPN gateway connection could not be found.
No Sample Response
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
name
property matching the exact specified name.A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
curl -X GET "$vpc_api_endpoint/v1/vpn_servers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVPNServersOptions := &vpcv1.ListVPNServersOptions{} vpnServerCollection, response, err := vpcService.ListVPNServers( listVPNServersOptions, )
ListVpnServersOptions listVpnServersOptions = new ListVpnServersOptions.Builder() .build(); Response<VPNServerCollection> response = vpcService.listVpnServers(listVpnServersOptions).execute(); VPNServerCollection vpnServerCollection = response.getResult();
const response = await vpcService.listVpnServers({});
vpn_server_collection = vpc_service.list_vpn_servers().get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
Collection of VPN servers
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers?start=ffd653466e284937896724b2dd044c9c&limit=20
next
Status Code
The VPN servers were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers?limit=50" }, "limit": 50, "total_count": 2, "vpn_servers": [ { "certificate": { "crn": "crn:[...]" }, "client_authentication": [ { "client_ca": { "crn": "crn:[...]" }, "crl": "crl", "method": "certificate" } ], "client_auto_delete": true, "client_auto_delete_timeout": 1, "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "client_idle_timeout": 10, "client_ip_pool": "192.168.0.0/16", "created_at": "2021-01-13T17:29:36.921569Z", "crn": "crn:[...]", "enable_split_tunneling": false, "health_reasons": [], "health_state": "ok", "hostname": "a4841334.us-south.vpn-server.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-1", "port": 443, "private_ips": [ { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.1.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e/reserved_ips/0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "id": "0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "protocol": "udp", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_server", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-0328643c-33a4-47b1-aff9-17820303c444", "id": "r006-0328643c-33a4-47b1-aff9-17820303c444", "name": "before-entrance-mountain-paralegal-photo-uninstall", "resource_type": "security_group" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "subnet-1", "resource_type": "subnet" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "name": "subnet-2", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "id": "r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "name": "my-vpc", "resource_type": "vpc" } }, { "certificate": { "crn": "crn:[...]" }, "client_authentication": [ { "identity_provider": { "provider_type": "iam" }, "method": "username" }, { "client_ca": { "crn": "crn:[...]" }, "crl": "crl", "method": "certificate" } ], "client_auto_delete": true, "client_auto_delete_timeout": 1, "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "client_idle_timeout": 10, "client_ip_pool": "192.168.0.0/16", "created_at": "2021-01-13T17:29:36.921569Z", "crn": "crn:[...]", "enable_split_tunneling": false, "health_reasons": [], "health_state": "ok", "hostname": "badc3b88.us-south.vpn-server.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-badc3b88-b9c2-46c3-acb1-2fd4361f6f7d", "id": "r006-badc3b88-b9c2-46c3-acb1-2fd4361f6f7d", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-2", "port": 443, "private_ips": [ { "address": "10.0.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-236a7fcf-3f9b-4612-8827-e7eddd216b6b", "id": "0716-236a7fcf-3f9b-4612-8827-e7eddd216b6b", "name": "my-reserved-ip-3", "resource_type": "subnet_reserved_ip" }, { "address": "10.1.0.42", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e/reserved_ips/0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "id": "0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "name": "my-reserved-ip-4", "resource_type": "subnet_reserved_ip" } ], "protocol": "udp", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_server", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-0328643c-33a4-47b1-aff9-17820303c444", "id": "r006-0328643c-33a4-47b1-aff9-17820303c444", "name": "before-entrance-mountain-paralegal-photo-uninstall", "resource_type": "security_group" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "subnet-1", "resource_type": "subnet" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "name": "subnet-2", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-e33d2b24-ffd4-49a2-acbf-e4e57c4a9dca", "id": "r134-e33d2b24-ffd4-49a2-acbf-e4e57c4a9dca", "name": "my-vpc-2", "resource_type": "vpc" } } ] }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN server prototype
The certificate instance for this VPN server.
Examples:ViewThe CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate
The methods used to authenticate VPN clients to this VPN server. VPN clients must authenticate against all specified methods.
Possible values: number of items ≥ 1, contains only unique items
client_authentication
The VPN client IPv4 address pool, expressed in CIDR format. The request must not overlap with any existing address prefixes in the VPC or any of the following reserved address ranges:
127.0.0.0/8
(IPv4 loopback addresses)161.26.0.0/16
(IBM services)166.8.0.0/14
(Cloud Service Endpoints)169.254.0.0/16
(IPv4 link-local addresses)224.0.0.0/4
(IPv4 multicast addresses)
The prefix length of the client IP address pool's CIDR must be between
/9
(8,388,608 addresses) and/22
(1024 addresses). A CIDR block that contains twice the number of IP addresses that are required to enable the maximum number of concurrent connections is recommended.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
The subnets to provision this VPN server in. Use subnets in different zones for high availability.
Possible values: 1 ≤ number of items ≤ 2, contains only unique items
subnets
The DNS server addresses that will be provided to VPN clients connected to this VPN server.
Possible values: number of items ≤ 2, contains only unique items
The seconds a VPN client can be idle before this VPN server will disconnect it. Specify
0
to prevent the server from disconnecting idle clients.Possible values: 0 ≤ value ≤ 28800
Default:
600
Example:
600
Indicates whether the split tunneling is enabled on this VPN server.
Default:
false
The name for this VPN server. The name must not be used by another VPN server in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-server
The port number to use for this VPN server.
Possible values: 1 ≤ value ≤ 65535
Default:
443
Example:
443
The transport protocol to use for this VPN server.
Allowable values: [
tcp
,udp
]Default:
udp
Example:
udp
The resource group to use. If unspecified, the account's default resource group will be used.
The security groups to use for this VPN server. If unspecified, the VPC's default security group is used.
Possible values: contains only unique items
Examples:Viewsecurity_groups
curl -X POST "$vpc_api_endpoint/v1/vpn_servers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "client_authentication": [ { "method": "username", "identity_provider": { "provider_type": "iam" } } ], "client_ip_pool": "172.16.0.0/16", "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "certificate": { "crn": "crn" }, "client_idle_timeout": 10, "name": "my-vpn-server", "port": 443, "protocol": "udp", "enable_split_tunneling": false, "security_groups": [ { "id": "r006-0328643c-33a4-47b1-aff9-17820303c444" } ], "subnets": [ { "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401" }, { "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e" } ] }'
certificateInstanceIdentityModel := &vpcv1.CertificateInstanceIdentityByCRN{ CRN: certificateCRN, // Provide valid CRN of the certificate } vpnServerAuthenticationByUsernameIDProviderModel := &vpcv1.VPNServerAuthenticationByUsernameIDProviderByIam { ProviderType: &[]string{"iam"}[0], } vpnServerAuthenticationPrototypeModel := &vpcv1.VPNServerAuthenticationPrototypeVPNServerAuthenticationByUsernamePrototype { Method: &[]string{"certificate"}[0], IdentityProvider: vpnServerAuthenticationByUsernameIDProviderModel, } subnetIdentityModel := &vpcv1.SubnetIdentityByID{ ID: &subnetId, // Provide a valid subnet Id } createVPNServerOptions := &vpcv1.CreateVPNServerOptions{ Certificate: certificateInstanceIdentityModel, ClientAuthentication: []vpcv1.VPNServerAuthenticationPrototypeIntf{ vpnServerAuthenticationPrototypeModel, }, ClientIPPool: &[]string{"172.16.0.0/16"}[0], Subnets: []vpcv1.SubnetIdentityIntf{subnetIdentityModel}, Name: &[]string{"my-vpn-server"}[0], } vpnServer, response, err := vpcService.CreateVPNServer( createVPNServerOptions, )
CertificateInstanceIdentityByCRN certificateInstanceIdentityModel = new CertificateInstanceIdentityByCRN.Builder() .crn(certificateCRN) .build(); VPNServerAuthenticationByUsernameIdProviderByIAM vpnServerAuthenticationByUsernameIdProviderModel = new VPNServerAuthenticationByUsernameIdProviderByIAM.Builder() .providerType("iam") .build(); VPNServerAuthenticationPrototypeVPNServerAuthenticationByUsernamePrototype vpnServerAuthenticationPrototypeModel = new VPNServerAuthenticationPrototypeVPNServerAuthenticationByUsernamePrototype.Builder() .method("certificate") .identityProvider(vpnServerAuthenticationByUsernameIdProviderModel) .build(); SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); CreateVpnServerOptions createVpnServerOptions = new CreateVpnServerOptions.Builder() .certificate(certificateInstanceIdentityModel) .clientAuthentication(new java.util.ArrayList<VPNServerAuthenticationPrototype>(java.util.Arrays.asList(vpnServerAuthenticationPrototypeModel))) .clientIpPool("172.16.0.0/16") .name("my-vpn-server") .subnets(new java.util.ArrayList<SubnetIdentity>(java.util.Arrays.asList(subnetIdentityModel))) .build(); Response<VPNServer> response = vpcService.createVpnServer(createVpnServerOptions).execute(); VPNServer vpnServer = response.getResult();
const certificateInstanceIdentityModel = { crn: certificateCRN, }; const vpnServerAuthenticationByUsernameIdProviderModel = { provider_type: 'iam', }; const vpnServerAuthenticationPrototypeModel = { method: 'certificate', identity_provider: vpnServerAuthenticationByUsernameIdProviderModel, }; const subnetIdentityModel = { id: subnetId, }; const params = { name: 'my-vpn-server', certificate: certificateInstanceIdentityModel, clientAuthentication: [vpnServerAuthenticationPrototypeModel], clientIpPool: '172.16.0.0/16', subnets: [subnetIdentityModel], }; const response = await vpcService.createVpnServer(params);
certificate_instance_identity_model = { 'crn': certificate_crn, } vpn_server_authentication_by_username_id_provider_model = { 'provider_type': 'iam', } vpn_server_authentication_prototype_model = { 'method': 'certificate', 'identity_provider': vpn_server_authentication_by_username_id_provider_model, } subnet_identity_model = { 'id': subnetId, } vpn_server = vpc_service.create_vpn_server( certificate=certificate_instance_identity_model, client_authentication=[vpn_server_authentication_prototype_model], client_ip_pool='172.16.0.0/16', subnets=[subnet_identity_model], name='my-vpn-server' ).get_result()
Response
The certificate instance for this VPN server.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate
The methods used to authenticate VPN clients to this VPN server. VPN clients must authenticate against all specified methods.
Possible values: number of items ≥ 1, contains only unique items
client_authentication
Indicates whether disconnected VPN clients will be automatically deleted after
client_auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
client_auto_delete
istrue
, the hours after which disconnected VPN clients will be automatically deleted. If the value is0
, disconnected VPN clients will be deleted immediately. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 24
Example:
1
The DNS server addresses that will be provided to VPN clients that are connected to this VPN server.
Possible values: contains only unique items
The seconds a VPN client can be idle before this VPN server will disconnect it. If
0
, the server will not disconnect idle clients.Possible values: 0 ≤ value ≤ 28800
Example:
600
The VPN client IPv4 address pool, expressed in CIDR format.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
The date and time that the VPN server was created.
The CRN for this VPN server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn-server:r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
Indicates whether the split tunneling is enabled on this VPN server.
Example:
true
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
Fully qualified domain name assigned to this VPN server
Example:
a8506291.us-south.vpn-server.appdomain.cloud
The URL for this VPN server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this VPN server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN server. The name is unique across all VPN servers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-server
The port number used by this VPN server.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The reserved IPs bound to this VPN server.
The transport protocol used by this VPN server.
Possible values: [
tcp
,udp
]Example:
udp
The resource group for this VPN server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this VPN server.
Possible values: number of items ≥ 1, contains only unique items
The subnets this VPN server is provisioned in.
The VPC this VPN server resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The VPN server was created successfully.
An invalid VPN server prototype object was provided.
The VPN server prototype object specifies a subnet with no available IP addresses, or a client address pool that overlaps with an address prefix in this VPC.
{ "certificate": { "crn": "crn:[...]" }, "client_authentication": [ { "identity_provider": { "provider_type": "iam" }, "method": "username" } ], "client_auto_delete": true, "client_auto_delete_timeout": 1, "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "client_idle_timeout": 10, "client_ip_pool": "192.168.0.0/16", "created_at": "2021-01-13T17:29:36.921569Z", "crn": "crn:[...]", "enable_split_tunneling": false, "health_reasons": [], "health_state": "ok", "hostname": "a4841334.us-south.vpn-server.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-1", "port": 443, "private_ips": [ { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.1.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e/reserved_ips/0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "id": "0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "protocol": "udp", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_server", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-0328643c-33a4-47b1-aff9-17820303c444", "id": "r006-0328643c-33a4-47b1-aff9-17820303c444", "name": "before-entrance-mountain-paralegal-photo-uninstall", "resource_type": "security_group" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "subnet-1", "resource_type": "subnet" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "name": "subnet-2", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "id": "r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "name": "my-vpc", "resource_type": "vpc" } }
Delete a VPN server
This request deletes a VPN server. This operation cannot be reversed.
DELETE /vpn_servers/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVPNServerOptions := vpcService.NewDeleteVPNServerOptions( vpnServerID, ) deleteVPNServerOptions.SetIfMatch(vpnServerETag) response, err := vpcService.DeleteVPNServer( deleteVPNServerOptions, )
DeleteVpnServerOptions deleteVpnServerOptions = new DeleteVpnServerOptions.Builder() .id(vpnServerId) .ifMatch(vpnServerETag) .build(); Response<Void> response = vpcService.deleteVpnServer(deleteVpnServerOptions).execute();
const params = { id: vpnServerId, ifMatch: vpnServerETag, }; const response = await vpcService.deleteVpnServer(params);
response = vpc_service.delete_vpn_server( id=vpnServerId, if_match=vpnServerETag )
Retrieve a VPN server
This request retrieves a single VPN server specified by the identifier in the URL.
GET /vpn_servers/{id}
Request
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVPNServerOptions := &vpcv1.GetVPNServerOptions{ ID: &vpnServerID, // Provide a valid VPN Server ID } vpnServer, response, err := vpcService.GetVPNServer( getVPNServerOptions, ) vpnServerETag = response.Headers.Get("ETag")
GetVpnServerOptions getVpnServerOptions = new GetVpnServerOptions.Builder() .id(vpnServerId) .build(); Response<VPNServer> response = vpcService.getVpnServer(getVpnServerOptions).execute(); VPNServer vpnServer = response.getResult(); String vpnServerETag = response.getHeaders().values("ETag").get(0);
const params = { id: vpnServerId, }; const response = await vpcService.getVpnServer(params); const vpnServerETag = response.headers.ETag
vpn_server_response = vpc_service.get_vpn_server( id=vpnServerId ) vpnServerETag = vpn_server_response.get_headers()['ETag'] vpn_server = vpn_server_response.get_result()
Response
The certificate instance for this VPN server.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate
The methods used to authenticate VPN clients to this VPN server. VPN clients must authenticate against all specified methods.
Possible values: number of items ≥ 1, contains only unique items
client_authentication
Indicates whether disconnected VPN clients will be automatically deleted after
client_auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
client_auto_delete
istrue
, the hours after which disconnected VPN clients will be automatically deleted. If the value is0
, disconnected VPN clients will be deleted immediately. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 24
Example:
1
The DNS server addresses that will be provided to VPN clients that are connected to this VPN server.
Possible values: contains only unique items
The seconds a VPN client can be idle before this VPN server will disconnect it. If
0
, the server will not disconnect idle clients.Possible values: 0 ≤ value ≤ 28800
Example:
600
The VPN client IPv4 address pool, expressed in CIDR format.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
The date and time that the VPN server was created.
The CRN for this VPN server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn-server:r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
Indicates whether the split tunneling is enabled on this VPN server.
Example:
true
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
Fully qualified domain name assigned to this VPN server
Example:
a8506291.us-south.vpn-server.appdomain.cloud
The URL for this VPN server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this VPN server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN server. The name is unique across all VPN servers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-server
The port number used by this VPN server.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The reserved IPs bound to this VPN server.
The transport protocol used by this VPN server.
Possible values: [
tcp
,udp
]Example:
udp
The resource group for this VPN server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this VPN server.
Possible values: number of items ≥ 1, contains only unique items
The subnets this VPN server is provisioned in.
The VPC this VPN server resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The VPN server was retrieved successfully.
A VPN server with the specified identifier could not be found.
{ "certificate": { "crn": "crn:[...]" }, "client_authentication": [ { "client_ca": { "crn": "crn:[...]" }, "crl": "crl", "method": "certificate" } ], "client_auto_delete": true, "client_auto_delete_timeout": 1, "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "client_idle_timeout": 10, "client_ip_pool": "192.168.0.0/16", "created_at": "2021-01-13T17:29:36.921569Z", "crn": "crn:[...]", "enable_split_tunneling": false, "health_reasons": [], "health_state": "ok", "hostname": "a4841334.us-south.vpn-server.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-1", "port": 443, "private_ips": [ { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.1.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e/reserved_ips/0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "id": "0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "protocol": "udp", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_server", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-0328643c-33a4-47b1-aff9-17820303c444", "id": "r006-0328643c-33a4-47b1-aff9-17820303c444", "name": "before-entrance-mountain-paralegal-photo-uninstall", "resource_type": "security_group" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "subnet-1", "resource_type": "subnet" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "name": "subnet-2", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "id": "r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "name": "my-vpc", "resource_type": "vpc" } }
Update a VPN server
This request updates the properties of an existing VPN server. Any property changes will cause all connected VPN clients are disconnected from this VPN server except for the name change.
PATCH /vpn_servers/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN server patch
The certificate instance for this VPN server.
Examples:ViewThe CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate
The authentication methods to use to authenticate VPN client on this VPN server (replacing any existing methods).
Possible values: number of items ≥ 1, contains only unique items
client_authentication
The DNS server addresses that will be provided to VPN clients connected to this VPN server (replacing any existing addresses).
Possible values: number of items ≤ 2, contains only unique items
The seconds a VPN client can be idle before this VPN server will disconnect it. If
0
, the server will not disconnect idle clients.Possible values: 0 ≤ value ≤ 28800
Example:
600
The VPN client IPv4 address pool, expressed in CIDR format. The request must not overlap with any existing address prefixes in the VPC or any of the following reserved address ranges:
127.0.0.0/8
(IPv4 loopback addresses)161.26.0.0/16
(IBM services)166.8.0.0/14
(Cloud Service Endpoints)169.254.0.0/16
(IPv4 link-local addresses)224.0.0.0/4
(IPv4 multicast addresses)
The prefix length of the client IP address pool's CIDR must be between
/9
(8,388,608 addresses) and/22
(1024 addresses). A CIDR block that contains twice the number of IP addresses that are required to enable the maximum number of concurrent connections is recommended.Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
Indicates whether the split tunneling is enabled on this VPN server.
Example:
true
The name for this VPN server. The name must not be used by another VPN server in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-server
The port number used by this VPN server.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The transport protocol used by this VPN server.
Allowable values: [
tcp
,udp
]Example:
udp
The subnets to provision this VPN server in (replacing the existing subnets).
Possible values: 1 ≤ number of items ≤ 2, contains only unique items
subnets
curl -X PATCH "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-vpn-server-1-updated" }'
options := &vpcv1.UpdateVPNServerOptions{ ID: &vpnServerID, // Provide a valid VPN Server ID } vpnServerPatchModel := &vpcv1.VPNServerPatch{ Name: &[]string{"my-vpn-server-updated"}[0], } vpnServerPatchModelAsPatch, asPatchErr := vpnServerPatchModel.AsPatch() options.VPNServerPatch = vpnServerPatchModelAsPatch vpnServer, response, err := vpcService.UpdateVPNServer(options)
VPNServerPatch vpnServerPatchModel = new VPNServerPatch.Builder() .name("my-vpn-server-updated") .build(); Map<String, Object> vpnServerPatchModelAsPatch = vpnServerPatchModel.asPatch(); UpdateVpnServerOptions updateVpnServerOptions = new UpdateVpnServerOptions.Builder() .id(vpnServerId) .vpnServerPatch(vpnServerPatchModelAsPatch) .ifMatch(vpnServerETag) .build(); Response<VPNServer> response = vpcService.updateVpnServer(updateVpnServerOptions).execute(); VPNServer vpnServer = response.getResult();
const params = { id: vpnServerId, name: 'my-vpn-server-updated', ifMatch: vpnServerETag, }; const = await vpcService.updateVpnServer(params);
vpn_server_patch_model = {} vpn_server_patch_model['name']='my-vpn-server-updated' vpn_server = vpc_service.update_vpn_server( id=vpnServerId, vpn_server_patch=vpn_server_patch_model, if_match=vpnServerETag ).get_result()
Response
The certificate instance for this VPN server.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate
The methods used to authenticate VPN clients to this VPN server. VPN clients must authenticate against all specified methods.
Possible values: number of items ≥ 1, contains only unique items
client_authentication
Indicates whether disconnected VPN clients will be automatically deleted after
client_auto_delete_timeout
hours have passed. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
If
client_auto_delete
istrue
, the hours after which disconnected VPN clients will be automatically deleted. If the value is0
, disconnected VPN clients will be deleted immediately. This value may be modifiable in the future.Possible values: 0 ≤ value ≤ 24
Example:
1
The DNS server addresses that will be provided to VPN clients that are connected to this VPN server.
Possible values: contains only unique items
The seconds a VPN client can be idle before this VPN server will disconnect it. If
0
, the server will not disconnect idle clients.Possible values: 0 ≤ value ≤ 28800
Example:
600
The VPN client IPv4 address pool, expressed in CIDR format.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
The date and time that the VPN server was created.
The CRN for this VPN server
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpn-server:r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
Indicates whether the split tunneling is enabled on this VPN server.
Example:
true
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
Fully qualified domain name assigned to this VPN server
Example:
a8506291.us-south.vpn-server.appdomain.cloud
The URL for this VPN server
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this VPN server
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN server.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN server. The name is unique across all VPN servers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-server
The port number used by this VPN server.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The reserved IPs bound to this VPN server.
The transport protocol used by this VPN server.
Possible values: [
tcp
,udp
]Example:
udp
The resource group for this VPN server
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
vpn_server
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this VPN server.
Possible values: number of items ≥ 1, contains only unique items
The subnets this VPN server is provisioned in.
The VPC this VPN server resides in.
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The VPN server was updated successfully.
An invalid VPN server patch was provided.
The VPN server is not allowed to be updated.
A VPC with the specified identifier could not be found.
The VPN server cannot be updated while it is being deleted, or the client address pool overlaps with an address prefix in this VPC.
The provided
If-Match
value does not match the current ETag value of the VPN server.
{ "certificate": { "crn": "crn:[...]" }, "client_authentication": [ { "client_ca": { "crn": "crn:[...]" }, "crl": "crl", "method": "certificate" } ], "client_auto_delete": true, "client_auto_delete_timeout": 1, "client_dns_server_ips": [ { "address": "161.26.0.7" }, { "address": "161.26.0.8" } ], "client_idle_timeout": 10, "client_ip_pool": "192.168.0.0/16", "created_at": "2021-01-13T17:29:36.921569Z", "crn": "crn:[...]", "enable_split_tunneling": false, "health_reasons": [], "health_state": "ok", "hostname": "a4841334.us-south.vpn-server.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r006-a4841334-b584-4293-938e-3bc63b4a5b6a", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-1-updated", "port": 443, "private_ips": [ { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0717-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0717-bb7e061d-7259-45b6-a0da-416ace665269", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.1.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e/reserved_ips/0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "id": "0727-4f7c5a3b-a5fb-4994-8a53-7efefc5f659f", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "protocol": "udp", "resource_group": { "crn": "crn:[...]", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "vpn_server", "security_groups": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/r006-0328643c-33a4-47b1-aff9-17820303c444", "id": "r006-0328643c-33a4-47b1-aff9-17820303c444", "name": "before-entrance-mountain-paralegal-photo-uninstall", "resource_type": "security_group" } ], "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "id": "0717-b28a7e6d-a66b-4de7-8713-15dcffdce401", "name": "subnet-1", "resource_type": "subnet" }, { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "id": "0727-0ec8d4aa-e0c0-4d1a-b772-26176603221e", "name": "subnet-2", "resource_type": "subnet" } ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "id": "r134-19c4284e-ce22-4d1c-a4c6-f1e15c7f7d55", "name": "my-vpc", "resource_type": "vpc" } }
Retrieve client configuration
This request retrieves OpenVPN client configuration on a single VPN server specified by the identifier in the URL. This configuration includes directives compatible with OpenVPN releases 2.4 and 2.5
GET /vpn_servers/{id}/client_configuration
Request
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/client_configuration?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVPNServerClientConfigurationOptions := &vpcv1.GetVPNServerClientConfigurationOptions{ ID: &vpnServerID, // Provide a valid VPN Server ID } vpnServerClientConfiguration, response, err := vpcService.GetVPNServerClientConfiguration( getVPNServerClientConfigurationOptions, )
GetVpnServerClientConfigurationOptions getVpnServerClientConfigurationOptions = new GetVpnServerClientConfigurationOptions.Builder() .id(vpnServerId) .build(); Response<String> response = vpcService.getVpnServerClientConfiguration(getVpnServerClientConfigurationOptions).execute(); String vpnServerClientConfiguration = response.getResult();
const params = { id: vpnServerId, }; const response = await vpcService.getVpnServerClientConfiguration(params);
vpn_server_client_configuration = vpc_service.get_vpn_server_client_configuration( id=vpnServerId ).get_result()
Response
Status Code
The client configuration was retrieved successfully.
A VPN server with the specified identifier could not be found.
The media type specified in
Accept
request header is not acceptable. Only the media typetext/plain
is supported.
client proto udp remote a8506291.us-south.vpn-server.appdomain.cloud port 443 dev tun nobind
-----BEGIN CERTIFICATE----- xxxxxx -----END CERTIFICATE-----
List all VPN clients for a VPN server
This request retrieves all connected VPN clients, and any disconnected VPN clients that the VPN server has not yet deleted based on its auto-deletion policy.
GET /vpn_servers/{vpn_server_id}/clients
Request
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order.Allowable values: [
created_at
]Default:
-created_at
Example:
created_at
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/clients?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVPNServerClientsOptions := &vpcv1.ListVPNServerClientsOptions{ VPNServerID: &vpnServerID, // Provide a valid VPN Server ID } vpnServerClientCollection, response, err := vpcService.ListVPNServerClients( listVPNServerClientsOptions, )
ListVpnServerClientsOptions listVpnServerClientsOptions = new ListVpnServerClientsOptions.Builder() .vpnServerId(vpnServerId) .build(); Response<VPNServerClientCollection> response = vpcService.listVpnServerClients(listVpnServerClientsOptions).execute(); VPNServerClientCollection vpnServerClientCollection = response.getResult();
const params = { vpnServerId: vpnServerId, }; const response = await vpcService.listVpnServerClients(params);
vpn_server_client_collection = vpc_service.list_vpn_server_clients( vpn_server_id=vpnServerId ).get_result()
Response
Collection of VPN clients
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531/clients?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531/clients?start=a5e812a2-62c0-4555-86a5-907106760c56&limit=20
next
Status Code
The VPN clients were retrieved successfully.
The specified VPN server could not be found.
{ "clients": [ { "client_ip": { "address": "192.168.0.2" }, "created_at": "2021-01-19T04:42:42Z", "data_received": 2000, "data_sent": 3000, "disconnected_at": "2021-01-23T04:08:10Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a/clients/r006-f100dde3-a112-4fa8-a90c-100d4dad4889", "id": "r006-f100dde3-a112-4fa8-a90c-100d4dad4889", "remote_ip": { "address": "202.1.23.33" }, "remote_port": 54632, "resource_type": "vpn_server_client", "status": "connected", "username": "my-vpn-server-client-1" }, { "client_ip": { "address": "192.168.0.3" }, "created_at": "2021-01-19T04:42:42Z", "data_received": 2000, "data_sent": 3000, "disconnected_at": "2021-01-23T04:08:10Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/clients/r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "remote_ip": { "address": "202.1.23.36" }, "remote_port": 54638, "resource_type": "vpn_server_client", "status": "disconnected", "username": "my-vpn-server-client-2" } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-a4841334-b584-4293-938e-3bc63b4a5b6a/clients?limit=50" }, "limit": 50, "total_count": 2 }
Delete a VPN client
This request disconnects and deletes the VPN client from the VPN server. The VPN client may reconnect unless its authentication permissions for the configured authentication methods (such as its client certificate) have been revoked.
DELETE /vpn_servers/{vpn_server_id}/clients/{id}
Request
Path Parameters
The VPN server identifier
The VPN client identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/clients/$client_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVPNServerClientOptions := vpcService.NewDeleteVPNServerClientOptions( vpnServerID, // Provide valid VPN Server Id vpnClientID, // Provide valid VPN Server's client Id ) response, err := vpcService.DeleteVPNServerClient( deleteVPNServerClientOptions, )
DeleteVpnServerClientOptions deleteVpnServerClientOptions = new DeleteVpnServerClientOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerClientId) .build(); Response<Void> response = vpcService.deleteVpnServerClient(deleteVpnServerClientOptions).execute();
const params = { vpnServerId: vpnServerId, id: vpnServerClientId, }; const response = await vpcService.deleteVpnServerClient(params);
response = vpc_service.delete_vpn_server_client( vpn_server_id=vpnServerId, id=vpnServerClientId )
Retrieve a VPN client
This request retrieves a single VPN client specified by the identifier in the URL.
GET /vpn_servers/{vpn_server_id}/clients/{id}
Request
Path Parameters
The VPN server identifier
The VPN client identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/clients/$client_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVPNServerClientOptions := vpcService.NewGetVPNServerClientOptions( vpnServerID, // Provide valid VPN Server Id vpnClientID, // Provide valid VPN Server's client Id ) vpnServerClient, response, err := vpcService.GetVPNServerClient( getVPNServerClientOptions, )
GetVpnServerClientOptions getVpnServerClientOptions = new GetVpnServerClientOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerClientId) .build(); Response<VPNServerClient> response = vpcService.getVpnServerClient(getVpnServerClientOptions).execute(); VPNServerClient vpnServerClient = response.getResult();
const params = { vpnServerId: vpnServerId, id: vpnServerClientId, }; const response = await vpcService.getVpnServerClient(params);
vpn_server_client = vpc_service.get_vpn_server_client( vpn_server_id=vpnServerId, id=vpnServerClientId ).get_result()
Response
The IP address assigned to this VPN client from
client_ip_pool
.The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
client_ip
The date and time that the VPN client was created
The URL for this VPN client
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/8e454ead-0db7-48ac-9a8b-2698d8c470a7/clients/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this VPN client
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The remote IP address of this VPN client.
The IP address.
This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
remote_ip
The remote port of this VPN client.
Possible values: 1 ≤ value ≤ 65535
Example:
22
The resource type
Possible values: [
vpn_server_client
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the VPN client:
connected
: the VPN client isconnected
to this VPN server.disconnected
: the VPN client isdisconnected
from this VPN server.
The enumerated values for this property may expand in the future.
Possible values: [
connected
,disconnected
]The common name of client certificate that the VPN client provided when connecting to the server.
This property will be present only when the
certificate
client authentication method is enabled on the VPN server.Possible values: 1 ≤ length ≤ 64
The date and time that the VPN client was disconnected.
This property will be present only when the client
status
isdisconnected
.The username that this VPN client provided when connecting to the VPN server.
This property will be present only when the
username
client authentication method is enabled on the VPN server.
Status Code
The VPN client was retrieved successfully.
A VPN client with the specified identifier could not be found.
{ "client_ip": { "address": "192.168.0.2" }, "created_at": "2021-01-19T04:42:42Z", "data_received": 2000, "data_sent": 3000, "disconnected_at": "2021-01-23T04:08:10Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/clients/r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "remote_ip": { "address": "202.1.23.33" }, "remote_port": 54632, "resource_type": "vpn_server_client", "status": "connected", "username": "my-vpn-server-client-1" }
Disconnect a VPN client
This request disconnects the specified VPN client, and deletes the client according to the VPN server's auto-deletion policy. The VPN client may reconnect unless its authentication permissions for the configured authentication methods (such as its client certificate) have been revoked.
POST /vpn_servers/{vpn_server_id}/clients/{id}/disconnect
Request
Path Parameters
The VPN server identifier
The VPN client identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X POST "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/clients/$client_id/disconnect?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
disconnectVPNClientOptions := vpcService.NewDisconnectVPNClientOptions( vpnServerID, // Provide valid VPN Server Id vpnClientID, // Provide valid VPN Server's client Id ) response, err := vpcService.DisconnectVPNClient(disconnectVPNClientOptions)
DisconnectVpnClientOptions disconnectVpnClientOptions = new DisconnectVpnClientOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerClientId) .build(); Response<Void> response = vpcService.disconnectVpnClient(disconnectVpnClientOptions).execute();
const params = { vpnServerId: vpnServerId, id: vpnServerClientId, }; const response = await vpcService.disconnectVpnClient(params);
response = vpc_service.disconnect_vpn_client( vpn_server_id=vpnServerId, id=vpnServerClientId )
List all VPN routes for a VPN server
This request lists all VPN routes in a VPN server. All VPN routes are provided to the VPN client when the connection is established. Packets received from the VPN client will be dropped by the VPN server if there is no VPN route matching their specified destinations. All VPN routes must be unique within the VPN server.
GET /vpn_servers/{vpn_server_id}/routes
Request
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
created_at
,name
]Default:
-created_at
Example:
name
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
listVPNServerRoutesOptions := vpcService.NewListVPNServerRoutesOptions( vpnServerID, // Provide valid VPN Server Id ) vpnServerRouteCollection, response, err := vpcService.ListVPNServerRoutes( listVPNServerRoutesOptions, )
ListVpnServerRoutesOptions listVpnServerRoutesOptions = new ListVpnServerRoutesOptions.Builder() .vpnServerId(vpnServerId) .build(); Response<VPNServerRouteCollection> response = vpcService.listVpnServerRoutes(listVpnServerRoutesOptions).execute(); VPNServerRouteCollection vpnServerRouteCollection = response.getResult();
const params = { vpnServerId: vpnServerId, }; const response = await vpcService.listVpnServerRoutes(params);
vpn_server_route_collection = vpc_service.list_vpn_server_routes( vpn_server_id=vpnServerId, sort='name' ).get_result()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routes?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of VPN routes
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-982d72b7-db1b-4606-afb2-ed6bd4b0bed1/routes?start=a5e812a2-62c0-4555-86a5-907106760c56&limit=20
next
Status Code
The VPN routes were retrieved successfully.
The specified VPN server could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-ebdc5374-2050-4f9e-a357-27b5a1a664cf/routes?limit=50" }, "limit": 50, "routes": [ { "action": "translate", "created_at": "2021-01-22T05:08:10Z", "destination": "192.0.2.0/24", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-ebdc5374-2050-4f9e-a357-27b5a1a664cf/routes/r006-f100dde3-a112-4fa8-a90c-100d4dad4889", "id": "r006-f100dde3-a112-4fa8-a90c-100d4dad4889", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-route-1", "resource_type": "vpn_server_route" }, { "action": "translate", "created_at": "2021-01-19T04:42:42Z", "destination": "192.0.3.0/24", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-route-2", "resource_type": "vpn_server_route" } ], "total_count": 2 }
Create a VPN route for a VPN server
This request creates a new VPN route in the VPN server. All VPN routes are provided to the VPN client when the connection is established. Packets received from the VPN client will be dropped by the VPN server if there is no VPN route matching their specified destinations. All VPN routes must be unique within the VPN server. destination of the packet.
POST /vpn_servers/{vpn_server_id}/routes
Request
Path Parameters
The VPN server identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN route prototype object
The destination to use for this VPN route in the VPN server. Must be unique within the VPN server. If an incoming packet does not match any destination, it will be dropped.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
172.16.0.0/16
The action to perform with a packet matching the VPN route:
translate
: translate the source IP address to one of the private IP addresses of the VPN server, then deliver the packet to target.deliver
: deliver the packet to the target.drop
: drop the packet
Allowable values: [
deliver
,drop
,translate
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
deliver
Example:
deliver
The name for this VPN server route. The name must not be used by another route for the VPN server. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-route-2
curl -X POST "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpn-server-route", "destination": "192.168.32.0/24", "action": "deliver" }'
createVPNServerRouteOptions := &vpcv1.CreateVPNServerRouteOptions{ VPNServerID: &vpnServerID, // Provide valid VPN Server Id Destination: &[]string{"172.16.0.0/16"}[0], Name: &[]string{"my-vpn-server-route"}[0], } createVPNServerRouteOptions.VPNServerID = &vpnServerID // Provide valid VPN Server Id vpnServerRoute, response, err := vpcService.CreateVPNServerRoute( createVPNServerRouteOptions, )
CreateVpnServerRouteOptions createVpnServerRouteOptions = new CreateVpnServerRouteOptions.Builder() .vpnServerId(vpnServerId) .destination("172.16.0.0/16") .name("my-vpn-server-route") .build(); Response<VPNServerRoute> response = vpcService.createVpnServerRoute(createVpnServerRouteOptions).execute(); VPNServerRoute vpnServerRoute = response.getResult();
const params = { vpnServerId: vpnServerId, destination: '172.16.0.0/16', name: 'my-vpn-server-route', }; const response = await vpcService.createVpnServerRoute(params);
vpn_server_route = vpc_service.create_vpn_server_route( vpn_server_id=vpnServerId, destination='172.16.0.0/16', name='my-vpn-server-route' ).get_result()
Response
The action to perform with a packet matching the VPN route:
translate
: translate the source IP address to one of the private IP addresses of the VPN server, then deliver the packet to target.deliver
: deliver the packet into the VPC.drop
: drop the packet
The enumerated values for this property may expand in the future.
Possible values: [
deliver
,drop
,translate
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
deliver
The date and time that the VPN route was created
The destination for this VPN route in the VPN server. If an incoming packet does not match any destination, it will be dropped.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPN route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this VPN route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN route. The name is unique across all routes for a VPN server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-route-1
The resource type
Possible values: [
vpn_server_route
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The VPN route was created successfully.
An invalid VPN route prototype object was provided.
The VPN route is not allowed to be created.
The specified VPN server could not be found.
The VPN route prototype object conflicts with another VPN route in the VPN server.
{ "action": "deliver", "created_at": "2021-01-27T04:53:41Z", "destination": "192.168.32.0/24", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-29dd63e4-250d-4cd1-88f3-b0e7dabd33fb/routes/r006-50ea9d54-ab06-4fc8-a9e0-c1b5e361420d", "id": "r006-29dd63e4-250d-4cd1-88f3-b0e7dabd33fb", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-route", "resource_type": "vpn_server_route" }
Delete a VPN route
This request deletes a VPN route. This operation cannot be reversed.
DELETE /vpn_servers/{vpn_server_id}/routes/{id}
Request
Path Parameters
The VPN server identifier
The VPN route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVPNServerRouteOptions := vpcService.NewDeleteVPNServerRouteOptions( vpnServerID, // Provide valid VPN Server Id vpnServerRouteID, // Provide valid VPN Server's route Id ) response, err := vpcService.DeleteVPNServerRoute( deleteVPNServerRouteOptions, )
DeleteVpnServerRouteOptions deleteVpnServerRouteOptions = new DeleteVpnServerRouteOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerRouteId) .build(); Response<Void> response = vpcService.deleteVpnServerRoute(deleteVpnServerRouteOptions).execute();
const params = { vpnServerId: vpnServerId, id: vpnServerRouteId, }; const response = await vpcService.deleteVpnServerRoute(params);
response = vpc_service.delete_vpn_server_route( vpn_server_id=vpnServerId, id=vpnServerRouteId )
Retrieve a VPN route
This request retrieves a single VPN route specified by the identifier in the URL.
GET /vpn_servers/{vpn_server_id}/routes/{id}
Request
Path Parameters
The VPN server identifier
The VPN route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
getVPNServerRouteOptions := vpcService.NewGetVPNServerRouteOptions( vpnServerID, vpnServerRouteID, ) vpnServerRoute, response, err := vpcService.GetVPNServerRoute( getVPNServerRouteOptions, )
GetVpnServerRouteOptions getVpnServerRouteOptions = new GetVpnServerRouteOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerRouteId) .build(); Response<VPNServerRoute> response = vpcService.getVpnServerRoute(getVpnServerRouteOptions).execute(); VPNServerRoute vpnServerRoute = response.getResult();
const params = { vpnServerId: vpnServerId, id: vpnServerRouteId, }; const response = await vpcService.getVpnServerRoute(params);
vpn_server_route = vpc_service.get_vpn_server_route( vpn_server_id=vpnServerId, id=vpnServerRouteId ).get_result()
Response
The action to perform with a packet matching the VPN route:
translate
: translate the source IP address to one of the private IP addresses of the VPN server, then deliver the packet to target.deliver
: deliver the packet into the VPC.drop
: drop the packet
The enumerated values for this property may expand in the future.
Possible values: [
deliver
,drop
,translate
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
deliver
The date and time that the VPN route was created
The destination for this VPN route in the VPN server. If an incoming packet does not match any destination, it will be dropped.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPN route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this VPN route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN route. The name is unique across all routes for a VPN server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-route-1
The resource type
Possible values: [
vpn_server_route
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The VPN route was retrieved successfully.
A VPN route with the specified identifier could not be found.
{ "action": "deliver", "created_at": "2021-01-19T04:42:42Z", "destination": "192.0.2.0/24", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-128c1fcf-79bc-40d0-88a1-b7c58f05cf5b/routes/r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "id": "r006-9cdddd42-8ce1-4ca9-ba65-06ffd4d6cf19", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-route-1", "resource_type": "vpn_server_route" }
Update a VPN route
This request updates a VPN route with the information in a provided VPN route patch. The VPN route patch object is structured in the same way as a retrieved VPN route and contains only the information to be updated.
PATCH /vpn_servers/{vpn_server_id}/routes/{id}
Request
Path Parameters
The VPN server identifier
The VPN route identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The VPN route patch
The name for this VPN server route. The name must not be used by another route for the VPN server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-vpn-route-2
curl -X PATCH "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-vpn-server-route-2" }'
vpnServerRoutePatchModel := &vpcv1.VPNServerRoutePatch{} vpnServerRoutePatchModel["name"] = "my-vpn-server-route-updated" vpnServerRoutePatchModelAsPatch, asPatchErr := vpnServerRoutePatchModel.AsPatch() updateVPNServerRouteOptions := &vpcv1.UpdateVPNServerRouteOptions{ VPNServerID: &vpnServerID, // Provide valid VPN Server Id ID: &vpnServerRouteID, // Provide valid VPN Server's route Id VPNServerRoutePatch: vpnServerRoutePatchModelAsPatch, } vpnServerRoute, response, err := vpcService.UpdateVPNServerRoute( updateVPNServerRouteOptions, )
VPNServerRoutePatch vpnServerRoutePatchModel = new VPNServerRoutePatch.Builder() .name("my-vpn-server-route-updated") .build(); Map<String, Object> vpnServerRoutePatchModelAsPatch = vpnServerRoutePatchModel.asPatch(); UpdateVpnServerRouteOptions updateVpnServerRouteOptions = new UpdateVpnServerRouteOptions.Builder() .vpnServerId(vpnServerId) .id(vpnServerRouteId) .vpnServerRoutePatch(vpnServerRoutePatchModelAsPatch) .build(); Response<VPNServerRoute> response = vpcService.updateVpnServerRoute(updateVpnServerRouteOptions).execute(); VPNServerRoute vpnServerRoute = response.getResult();
const params = { vpnServerId: vpnServerId, id: vpnServerRouteId, name: 'my-vpn-server-route-updated', }; const response = await vpcService.updateVpnServerRoute(params);
vpn_server_route_patch_model = {} vpn_server_route_patch_model['name']='my-vpn-server-route-updated' vpn_server_route = vpc_service.update_vpn_server_route( vpn_server_id=vpnServerId, id=vpnServerRouteId, vpn_server_route_patch=vpn_server_route_patch_model ).get_result()
Response
The action to perform with a packet matching the VPN route:
translate
: translate the source IP address to one of the private IP addresses of the VPN server, then deliver the packet to target.deliver
: deliver the packet into the VPC.drop
: drop the packet
The enumerated values for this property may expand in the future.
Possible values: [
deliver
,drop
,translate
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
deliver
The date and time that the VPN route was created
The destination for this VPN route in the VPN server. If an incoming packet does not match any destination, it will be dropped.
Possible values: 9 ≤ length ≤ 18, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/(3[0-2]|[1-2][0-9]|[0-9]))$
Example:
192.168.3.0/24
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this VPN route
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-8e454ead-0db7-48ac-9a8b-2698d8c470a7/routes/r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The unique identifier for this VPN route
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a15dca5-7e33-45e1-b7c5-bc690e569531
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the VPN route
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this VPN route. The name is unique across all routes for a VPN server.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpn-route-1
The resource type
Possible values: [
vpn_server_route
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The VPN route was updated successfully.
An invalid VPN route patch was provided.
The VPN route is not allowed to be updated.
A VPN route with the specified identifier could not be found.
The VPN route cannot be updated while it is being deleted.
{ "action": "deliver", "created_at": "2021-01-19T04:43:26Z", "destination": "192.0.2.0/24", "health_reasons": [], "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_servers/r006-2a761c87-12f7-49cd-b243-307d32f1a88f/routes/r006-e2242305-87f7-4a35-88f5-aeca7914aad1", "id": "r006-e2242305-87f7-4a35-88f5-aeca7914aad1", "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-vpn-server-route-2", "resource_type": "vpn_server_route" }
List all load balancer profiles
This request lists all load balancer profiles available in the region. A load balancer profile specifies the performance characteristics and pricing model for a load balancer.
GET /load_balancer/profiles
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/load_balancer/profiles?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancersOptions{} response, response, err := vpcService.ListLoadBalancerProfiles(options)
ListLoadBalancerProfilesOptions listLoadBalancerProfilesOptions = new ListLoadBalancerProfilesOptions.Builder() .build(); Response<LoadBalancerProfileCollection> response = service.listLoadBalancerProfiles(listLoadBalancerProfilesOptions).execute(); LoadBalancerProfileCollection loadBalancerProfileCollection = response.getResult();
const response = await vpcService.listLoadBalancerProfiles();
response = service.list_load_balancer_profiles()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of load balancer profiles
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The load balancer profiles were retrieved successfully
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles?limit=50" }, "limit": 50, "profiles": [ { "availability": { "type": "fixed", "value": "region" }, "family": "network", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed", "instance_groups_supported": { "type": "fixed", "value": true }, "logging_supported": { "type": "fixed", "value": [] }, "name": "network-fixed", "route_mode_supported": { "type": "fixed", "value": true }, "security_groups_supported": { "type": "fixed", "value": false }, "source_ip_session_persistence_supported": { "type": "fixed", "value": false }, "udp_supported": { "type": "fixed", "value": true } } ], "total_count": 1 }
Retrieve a load balancer profile
This request retrieves a load balancer profile specified by the name in the URL.
GET /load_balancer/profiles/{name}
Request
Path Parameters
The load balancer profile name
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancer/profiles/$profile_name?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerProfileOptions{} options.SetName(name) response, response, err := vpcService.GetLoadBalancerProfile(options)
GetLoadBalancerProfileOptions getLoadBalancerProfileOptions = new GetLoadBalancerProfileOptions.Builder() .name(loadBalancerProfileName) .build(); Response<LoadBalancerProfile> response = service.getLoadBalancerProfile(getLoadBalancerProfileOptions).execute(); LoadBalancerProfile loadBalancerProfile = response.getResult();
const response = await vpcService.getLoadBalancerProfile({ profileName });
response = service.get_load_balancer_profile(name)
Response
The product family this load balancer profile belongs to.
The enumerated values for this property may expand in the future.
Possible values: [
application
,network
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
network
The URL for this load balancer profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed
Indicates which logging type(s) are supported for a load balancer with this profile
The globally unique name for this load balancer profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
network-fixed
Status Code
The load balancer profile was retrieved successfully
A load balancer profile with the specified name could not be found.
{ "availability": { "type": "fixed", "value": "region" }, "family": "network", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed", "instance_groups_supported": { "type": "fixed", "value": true }, "logging_supported": { "type": "fixed", "value": [] }, "name": "network-fixed", "route_mode_supported": { "type": "fixed", "value": true }, "security_groups_supported": { "type": "fixed", "value": false }, "source_ip_session_persistence_supported": { "type": "fixed", "value": false }, "udp_supported": { "type": "fixed", "value": true } }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/load_balancers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancersOptions{} response, response, err := vpcService.ListLoadBalancers(options)
ListLoadBalancersOptions listLoadBalancersOptions = new ListLoadBalancersOptions(); Response<LoadBalancerCollection> response = service.listLoadBalancers(listLoadBalancersOptions).execute(); LoadBalancerCollection loadBalancerCollection = response.getResult();
const response = await vpcService.listLoadBalancers();
response = service.list_load_balancers()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of load balancers
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The load balancers were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers?limit=50" }, "limit": 50, "load_balancers": [ { "availability": "region", "created_at": "2018-12-16T16:29:30.160929Z", "crn": "crn:[...]", "hostname": "7b6dc78d.lb.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca", "id": "7b6dc78d-49f3-435f-b767-e05f9affd3ca", "instance_groups_supported": true, "is_private_path": false, "is_public": true, "listeners": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/listeners/a8433879-cb79-4b62-af8f-7b3329eac465", "id": "a8433879-cb79-4b62-af8f-7b3329eac465" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/listeners/6a034f25-06b4-4cc3-8e3f-6a372616798b", "id": "6a034f25-06b4-4cc3-8e3f-6a372616798b" } ], "logging": { "datapath": { "active": true } }, "name": "my-load-balancer-1", "operating_status": "online", "pools": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/2c431ab3-0151-11e9-a178-22dd3503b06c", "id": "2c431ab3-0151-11e9-a178-22dd3503b06c", "name": "add-prod-servers-http" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/c3629207-014f-11e9-a178-22dd3503b06c", "id": "c3629207-014f-11e9-a178-22dd3503b06c", "name": "my-prod-servers-tcp" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/c35ce451-014f-11e9-a178-22dd3503b06c", "id": "c35ce451-014f-11e9-a178-22dd3503b06c", "name": "update-prod-servers-http" } ], "private_ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "profile": { "family": "application", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/dynamic", "name": "dynamic" }, "provisioning_status": "active", "public_ips": [ { "address": "192.0.0.56" }, { "address": "192.0.0.44" } ], "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/6eb23aa499254c66917dc265c374eca9", "id": "6eb23aa499254c66917dc265c374eca9", "name": "Default" }, "resource_type": "load_balancer", "route_mode": true, "security_groups": [], "security_groups_supported": false, "source_ip_session_persistence_supported": false, "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "udp_supported": true }, { "availability": "region", "created_at": "2018-12-13T18:00:11.896545Z", "crn": "crn:[...]", "hostname": "1bf28ca5.lb.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/1bf28ca5-3037-4b96-b4a0-f22e82eae3db", "id": "1bf28ca5-3037-4b96-b4a0-f22e82eae3db", "instance_groups_supported": true, "is_private_path": false, "is_public": true, "listeners": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/1bf28ca5-3037-4b96-b4a0-f22e82eae3db/listeners/72cdbc3e-f8ac-4c74-8b91-75a4e6648242", "id": "72cdbc3e-f8ac-4c74-8b91-75a4e6648242" } ], "logging": { "datapath": { "active": true } }, "name": "my-load-balancer-2", "operating_status": "online", "pools": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/1bf28ca5-3037-4b96-b4a0-f22e82eae3db/pools/efa7abe9-ff00-11e8-a9c9-5a9d1cc77531", "id": "efa7abe9-ff00-11e8-a9c9-5a9d1cc77531", "name": "pool-1" } ], "private_ips": [ { "address": "10.0.0.21", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.0.41", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "profile": { "family": "application", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/dynamic", "name": "dynamic" }, "provisioning_status": "active", "public_ips": [ { "address": "192.0.0.51" }, { "address": "192.0.0.55" } ], "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/6eb23aa499254c66917dc265c374eca9", "id": "6eb23aa499254c66917dc265c374eca9", "name": "Default" }, "resource_type": "load_balancer", "route_mode": true, "security_groups": [], "security_groups_supported": false, "source_ip_session_persistence_supported": false, "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "udp_supported": true } ], "total_count": 2 }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer prototype object
Indicates whether this load balancer is public.
At present,
- If route mode is enabled, the load balancer must be private.
- If
is_private_path
is specified, it must be set tofalse
.
Example:
true
The subnets to provision this load balancer in. The subnets must be in the same VPC.
- If 'availability' is specified as
subnet
in the profile, the load balancer's availability will depend on the availability of the zones that the subnets reside in. - If 'availability' is specified as
region
in the profile, the load balancer remains available as long as any zone in the region is available. Only members in healthy zones will be sent new connections.
Load balancers in the
network
family allow only one subnet to be specified.Possible values: 1 ≤ number of items ≤ 15, contains only unique items
subnets
- If 'availability' is specified as
The DNS configuration for this load balancer.
If unspecified, DNS
A
records for this load balancer'shostname
property will be added to the public DNS zonelb.appdomain.cloud
. Otherwise, those DNSA
records will be added to the specifiedzone
.Not supported by private path load balancers.
Indicates whether this is a private path load balancer.
Default:
false
Example:
true
The listeners of this load balancer
The logging configuration to use for this load balancer. See VPC Datapath Logging on the logging format, fields and permitted values. If unspecified,
datapath.active
will befalse
.To activate logging, the load balancer profile must support the specified logging type.
The datapath logging configuration for this load balancer.
logging
The name for this load balancer. The name must not be used by another load balancer in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer
The pools of this load balancer
The profile to use for this load balancer.
If unspecified,
application
will be used.The globally unique name for this load balancer profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
network-fixed
profile
The resource group to use. If unspecified, the account's default resource group will be used.
Indicates whether route mode is enabled for this load balancer.
At present, public load balancers are not supported with route mode enabled.
Default:
false
Example:
true
The security groups to use for this load balancer. If unspecified, the VPC's default security group is used.
The load balancer profile must support security groups.
Possible values: contains only unique items
Examples:Viewsecurity_groups
curl -X POST "$vpc_api_endpoint/v1/load_balancers?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-load-balancer", "is_public": true, "subnets": [ { "id": "0736-b497ed3b-51ab-41e0-afff-b50f9be53513" } ], "listeners": [ { "protocol": "http", "port": 65432, "default_pool": { "name": "my-pool" } } ], "pools": [ { "name": "my-pool", "protocol": "http", "algorithm": "round_robin", "health_monitor": { "type": "http", "delay": 5, "max_retries": 2, "timeout": 2, "url_path": "/" } } ] }'
options := &vpcv1.CreateLoadBalancerOptions{} options.SetIsPublic(true) options.SetName(name) var subnetArray = []vpcv1.SubnetIdentityIntf{ &vpcv1.SubnetIdentity{ ID: &subnetId, }, } options.SetSubnets(subnetArray) lb, response, err := vpcService.CreateLoadBalancer(options)
SubnetIdentityById subnetIdentityModel = new SubnetIdentityById.Builder() .id(subnetId) .build(); CreateLoadBalancerOptions createLoadBalancerOptions = new CreateLoadBalancerOptions.Builder() .name("my-load-balancer") .isPublic(true) .subnets(new java.util.ArrayList<SubnetIdentity>(java.util.Arrays.asList(subnetIdentityModel))) .build(); Response<LoadBalancer> response = service.createLoadBalancer(createLoadBalancerOptions).execute(); LoadBalancer loadBalancer = response.getResult();
const subnetIdentityModel = { id: subnetID, }; const params = { isPublic: true, subnets: [subnetIdentityModel], name: 'my-load-balancer', }; const response = await vpcService.createLoadBalancer(params);
subnet_identity_model = {} subnet_identity_model['id'] = subnet_id load_balancer_pool_identity_by_name_model = {} load_balancer_pool_identity_by_name_model[ 'name'] = 'my-load-balancer-pool' load_balancer_listener_prototype_load_balancer_context_model = {} load_balancer_listener_prototype_load_balancer_context_model[ 'connection_limit'] = 2000 load_balancer_listener_prototype_load_balancer_context_model[ 'default_pool'] = load_balancer_pool_identity_by_name_model load_balancer_listener_prototype_load_balancer_context_model[ 'port'] = 443 load_balancer_listener_prototype_load_balancer_context_model[ 'protocol'] = 'http' load_balancer_pool_member_target_prototype_model = {} load_balancer_pool_member_target_prototype_model[ 'address'] = '192.168.3.4' load_balancer_pool_health_monitor_prototype_model = {} load_balancer_pool_health_monitor_prototype_model['delay'] = 5 load_balancer_pool_health_monitor_prototype_model['max_retries'] = 2 load_balancer_pool_health_monitor_prototype_model['port'] = 22 load_balancer_pool_health_monitor_prototype_model['timeout'] = 2 load_balancer_pool_health_monitor_prototype_model['type'] = 'http' load_balancer_pool_health_monitor_prototype_model['url_path'] = '/' load_balancer_pool_member_prototype_model = {} load_balancer_pool_member_prototype_model['port'] = 80 load_balancer_pool_member_prototype_model[ 'target'] = load_balancer_pool_member_target_prototype_model load_balancer_pool_member_prototype_model['weight'] = 50 load_balancer_pool_session_persistence_prototype_model = {} load_balancer_pool_session_persistence_prototype_model[ 'type'] = 'source_ip' load_balancer_pool_prototype_model = {} load_balancer_pool_prototype_model['algorithm'] = 'least_connections' load_balancer_pool_prototype_model[ 'health_monitor'] = load_balancer_pool_health_monitor_prototype_model load_balancer_pool_prototype_model['members'] = [ load_balancer_pool_member_prototype_model ] load_balancer_pool_prototype_model['name'] = 'my-load-balancer-pool' load_balancer_pool_prototype_model['protocol'] = 'http' load_balancer_pool_prototype_model[ 'session_persistence'] = load_balancer_pool_session_persistence_prototype_model resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id is_public = True subnets = [subnet_identity_model] listeners = [ load_balancer_listener_prototype_load_balancer_context_model ] name = 'my-load-balancer' pools = [load_balancer_pool_prototype_model] resource_group = resource_group_identity_model response = service.create_load_balancer( is_public, subnets, listeners=listeners, name=name, pools=pools, resource_group=resource_group, )
Response
The availability of this load balancer:
subnet
: remains available if at least one zone that the load balancer's subnets reside in is availableregion
: remains available if at least one zone in the region is available.
The enumerated values for this property may expand in the future.
Possible values: [
region
,subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
region
The date and time that this load balancer was created
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Fully qualified domain name assigned to this load balancer
Example:
6b88d615-us-south.lb.appdomain.cloud
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Indicates whether this load balancer supports instance groups.
Example:
true
Indicates whether this is a private path load balancer.
Example:
true
The type of this load balancer, public or private
Example:
true
The listeners of this load balancer
The logging configuration for this load balancer.
The datapath logging configuration for this load balancer.
logging
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The operating status of this load balancer
Possible values: [
offline
,online
]The pools of this load balancer
The private IP addresses assigned to this load balancer.
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
private_ips
The profile for this load balancer
The product family this load balancer profile belongs to.
The enumerated values for this property may expand in the future.
Possible values: [
application
,network
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
network
The URL for this load balancer profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed
The globally unique name for this load balancer profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
network-fixed
profile
The provisioning status of this load balancer:
active
: The load balancer is running.create_pending
: The load balancer is being created.delete_pending
: The load balancer is being deleted.maintenance_pending
: The load balancer is unavailable due to an internal error (contact IBM support).migrate_pending
: The load balancer is migrating to the requested configuration. Performance may be degraded.update_pending
: The load balancer is being updated to the requested configuration.
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,maintenance_pending
,migrate_pending
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The public IP addresses assigned to this load balancer.
Applicable only for public load balancers.
The resource group for this load balancer
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether route mode is enabled for this load balancer.
At present, public load balancers are not supported with route mode enabled.
Example:
true
The security groups targeting this load balancer.
If empty, all inbound and outbound traffic is allowed.
Applicable only for load balancers that support security groups.
Possible values: contains only unique items
Indicates whether this load balancer supports security groups.
Indicates whether this load balancer supports source IP session persistence.
Example:
true
The subnets this load balancer is provisioned in. The load balancer's availability depends on the availability of the zones that the subnets reside in.
All subnets will be in the same VPC.
Indicates whether this load balancer supports UDP.
Example:
true
The DNS configuration for this load balancer.
If absent, DNS
A
records for this load balancer'shostname
property will be added to the public DNS zonelb.appdomain.cloud
.Not supported by private path load balancers.
Status Code
The load balancer was created successfully.
An invalid load balancer prototype object was provided.
A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.
{ "availability": "region", "created_at": "2018-12-16T16:29:30.160929Z", "crn": "crn:[...]", "hostname": "7b6dc78d.lb.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca", "id": "7b6dc78d-49f3-435f-b767-e05f9affd3ca", "instance_groups_supported": true, "is_private_path": false, "is_public": true, "listeners": [], "logging": { "datapath": { "active": false } }, "name": "my-load-balancer", "operating_status": "online", "pools": [], "private_ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "profile": { "family": "application", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/dynamic", "name": "dynamic" }, "provisioning_status": "active", "public_ips": [ { "address": "192.0.0.56" }, { "address": "192.0.0.44" } ], "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/6eb23aa499254c66917dc265c374eca9", "id": "6eb23aa499254c66917dc265c374eca9", "name": "Default" }, "resource_type": "load_balancer", "route_mode": true, "security_groups": [], "security_groups_supported": false, "source_ip_session_persistence_supported": false, "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "udp_supported": true }
Delete a load balancer
This request deletes a load balancer. This operation cannot be reversed.
A load balancer cannot be deleted if its provisioning_status
is delete_pending
or it
is referenced by a resource.
DELETE /load_balancers/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
deleteVpcOptions := &vpcv1.DeleteLoadBalancerOptions{} deleteVpcOptions.SetID(id) response, err := vpcService.DeleteLoadBalancer(deleteVpcOptions)
DeleteLoadBalancerOptions deleteLoadBalancerOptions = new DeleteLoadBalancerOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteLoadBalancer(deleteLoadBalancerOptions).execute();
const response = await vpcService.deleteLoadBalancer({id});
response = service.delete_load_balancer(id)
Response
Status Code
The load balancer deletion request was accepted.
A load balancer with the specified identifier could not be found.
The load balancer cannot be deleted because it is in its current state, it is in use, or it is referenced by another resource
The provided
If-Match
value does not match the current ETag value of the load balancer.
No Sample Response
Retrieve a load balancer
This request retrieves a single load balancer specified by the identifier in the URL path.
GET /load_balancers/{id}
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerOptions{} options.SetID(id) lb, response, err := vpcService.GetLoadBalancer(options)
GetLoadBalancerOptions getLoadBalancerOptions = new GetLoadBalancerOptions.Builder() .id(id) .build(); Response<LoadBalancer> response = service.getLoadBalancer(getLoadBalancerOptions).execute(); LoadBalancer loadBalancer = response.getResult();
const response = await vpcService.getLoadBalancer({ id });
response = service.get_load_balancer(id)
Response
The availability of this load balancer:
subnet
: remains available if at least one zone that the load balancer's subnets reside in is availableregion
: remains available if at least one zone in the region is available.
The enumerated values for this property may expand in the future.
Possible values: [
region
,subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
region
The date and time that this load balancer was created
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Fully qualified domain name assigned to this load balancer
Example:
6b88d615-us-south.lb.appdomain.cloud
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Indicates whether this load balancer supports instance groups.
Example:
true
Indicates whether this is a private path load balancer.
Example:
true
The type of this load balancer, public or private
Example:
true
The listeners of this load balancer
The logging configuration for this load balancer.
The datapath logging configuration for this load balancer.
logging
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The operating status of this load balancer
Possible values: [
offline
,online
]The pools of this load balancer
The private IP addresses assigned to this load balancer.
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
private_ips
The profile for this load balancer
The product family this load balancer profile belongs to.
The enumerated values for this property may expand in the future.
Possible values: [
application
,network
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
network
The URL for this load balancer profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed
The globally unique name for this load balancer profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
network-fixed
profile
The provisioning status of this load balancer:
active
: The load balancer is running.create_pending
: The load balancer is being created.delete_pending
: The load balancer is being deleted.maintenance_pending
: The load balancer is unavailable due to an internal error (contact IBM support).migrate_pending
: The load balancer is migrating to the requested configuration. Performance may be degraded.update_pending
: The load balancer is being updated to the requested configuration.
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,maintenance_pending
,migrate_pending
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The public IP addresses assigned to this load balancer.
Applicable only for public load balancers.
The resource group for this load balancer
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether route mode is enabled for this load balancer.
At present, public load balancers are not supported with route mode enabled.
Example:
true
The security groups targeting this load balancer.
If empty, all inbound and outbound traffic is allowed.
Applicable only for load balancers that support security groups.
Possible values: contains only unique items
Indicates whether this load balancer supports security groups.
Indicates whether this load balancer supports source IP session persistence.
Example:
true
The subnets this load balancer is provisioned in. The load balancer's availability depends on the availability of the zones that the subnets reside in.
All subnets will be in the same VPC.
Indicates whether this load balancer supports UDP.
Example:
true
The DNS configuration for this load balancer.
If absent, DNS
A
records for this load balancer'shostname
property will be added to the public DNS zonelb.appdomain.cloud
.Not supported by private path load balancers.
Status Code
The load balancer was retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "availability": "region", "created_at": "2018-12-16T16:29:30.160929Z", "crn": "crn:[...]", "hostname": "7b6dc78d.lb.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca", "id": "7b6dc78d-49f3-435f-b767-e05f9affd3ca", "instance_groups_supported": true, "is_private_path": false, "is_public": true, "listeners": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/listeners/a8433879-cb79-4b62-af8f-7b3329eac465", "id": "a8433879-cb79-4b62-af8f-7b3329eac465" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/listeners/6a034f25-06b4-4cc3-8e3f-6a372616798b", "id": "6a034f25-06b4-4cc3-8e3f-6a372616798b" } ], "logging": { "datapath": { "active": true } }, "name": "my-load-balancer-1", "operating_status": "online", "pools": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/2c431ab3-0151-11e9-a178-22dd3503b06c", "id": "2c431ab3-0151-11e9-a178-22dd3503b06c", "name": "add-prod-servers-http" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/c3629207-014f-11e9-a178-22dd3503b06c", "id": "c3629207-014f-11e9-a178-22dd3503b06c", "name": "my-prod-servers-tcp" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca/pools/c35ce451-014f-11e9-a178-22dd3503b06c", "id": "c35ce451-014f-11e9-a178-22dd3503b06c", "name": "update-prod-servers-http" } ], "private_ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "profile": { "family": "application", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/dynamic", "name": "dynamic" }, "provisioning_status": "active", "public_ips": [ { "address": "192.0.0.56" }, { "address": "192.0.0.44" } ], "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/6eb23aa499254c66917dc265c374eca9", "id": "6eb23aa499254c66917dc265c374eca9", "name": "Default" }, "resource_type": "load_balancer", "route_mode": true, "security_groups": [], "security_groups_supported": false, "source_ip_session_persistence_supported": false, "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "udp_supported": true }
Update a load balancer
This request updates a load balancer with the information in a provided load balancer
patch. The load balancer patch object is structured in the same way as a retrieved load
balancer and contains only the information to be updated. A load balancer can only be
updated if its provisioning_status
is active
.
PATCH /load_balancers/{id}
Request
Custom Headers
If present, the request will fail if the specified ETag value does not match the resource's current ETag value. Required if the request body includes an array.
Possible values: 2 ≤ length ≤ 512, Value must match regular expression
(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"
Example:
W/"96d225c4-56bd-43d9-98fc-d7148e5c5028"
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer patch
The DNS configuration for this load balancer.
Specify
null
to remove the existing DNS configuration, which will remove all DNSA
records for this load balancer that had been added tozone
, and add equivalentA
records to the public DNS zonelb.appdomain.cloud
.Not supported by private path load balancers.
The logging configuration to use for this load balancer.
To activate logging, the load balancer profile must support the specified logging type.
The datapath logging configuration for this load balancer.
logging
The name for this load balancer. The name must not be used by another load balancer in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer
The subnets to provision this load balancer in. The load balancer's availability will depend on the availability of the zones that the subnets reside in.
The specified subnets must be in the same VPC as the existing subnets, and will completely replace the existing subnets.
The load balancer must be in the
application
family.Possible values: 1 ≤ number of items ≤ 15, contains only unique items
subnets
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-load-balancer-3", "logging": { "datapath": { "active": true } } }'
options := &vpcv1.UpdateLoadBalancerOptions{ Name: &name, } options.SetID(id) lb, response, err := vpcService.UpdateLoadBalancer(options)
UpdateLoadBalancerOptions updateLoadBalancerOptions = new UpdateLoadBalancerOptions.Builder() .id(id) .name(name) .build(); Response<LoadBalancer> response = service.updateLoadBalancer(updateLoadBalancerOptions).execute(); LoadBalancer loadBalancer = response.getResult();
const response = await vpcService.updateLoadBalancer({ id, name: 'my-load-balancer', });
response = service.update_load_balancer( id, name='my-load-balancer', )
Response
The availability of this load balancer:
subnet
: remains available if at least one zone that the load balancer's subnets reside in is availableregion
: remains available if at least one zone in the region is available.
The enumerated values for this property may expand in the future.
Possible values: [
region
,subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
region
The date and time that this load balancer was created
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Fully qualified domain name assigned to this load balancer
Example:
6b88d615-us-south.lb.appdomain.cloud
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
Indicates whether this load balancer supports instance groups.
Example:
true
Indicates whether this is a private path load balancer.
Example:
true
The type of this load balancer, public or private
Example:
true
The listeners of this load balancer
The logging configuration for this load balancer.
The datapath logging configuration for this load balancer.
logging
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The operating status of this load balancer
Possible values: [
offline
,online
]The pools of this load balancer
The private IP addresses assigned to this load balancer.
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
private_ips
The profile for this load balancer
The product family this load balancer profile belongs to.
The enumerated values for this property may expand in the future.
Possible values: [
application
,network
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
network
The URL for this load balancer profile
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/network-fixed
The globally unique name for this load balancer profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
network-fixed
profile
The provisioning status of this load balancer:
active
: The load balancer is running.create_pending
: The load balancer is being created.delete_pending
: The load balancer is being deleted.maintenance_pending
: The load balancer is unavailable due to an internal error (contact IBM support).migrate_pending
: The load balancer is migrating to the requested configuration. Performance may be degraded.update_pending
: The load balancer is being updated to the requested configuration.
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,maintenance_pending
,migrate_pending
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The public IP addresses assigned to this load balancer.
Applicable only for public load balancers.
The resource group for this load balancer
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether route mode is enabled for this load balancer.
At present, public load balancers are not supported with route mode enabled.
Example:
true
The security groups targeting this load balancer.
If empty, all inbound and outbound traffic is allowed.
Applicable only for load balancers that support security groups.
Possible values: contains only unique items
Indicates whether this load balancer supports security groups.
Indicates whether this load balancer supports source IP session persistence.
Example:
true
The subnets this load balancer is provisioned in. The load balancer's availability depends on the availability of the zones that the subnets reside in.
All subnets will be in the same VPC.
Indicates whether this load balancer supports UDP.
Example:
true
The DNS configuration for this load balancer.
If absent, DNS
A
records for this load balancer'shostname
property will be added to the public DNS zonelb.appdomain.cloud
.Not supported by private path load balancers.
Status Code
The load balancer was updated successfully.
An invalid load balancer patch was provided.
A load balancer with the specified identifier could not be found.
The load balancer cannot be updated in its current state.
The provided
If-Match
value does not match the current ETag value of the load balancer.
{ "availability": "region", "created_at": "2018-12-16T16:29:30.160929Z", "crn": "crn:[...]", "hostname": "7b6dc78d.lb.appdomain.cloud", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/7b6dc78d-49f3-435f-b767-e05f9affd3ca", "id": "7b6dc78d-49f3-435f-b767-e05f9affd3ca", "instance_groups_supported": true, "is_private_path": false, "is_public": true, "listeners": [], "logging": { "datapath": { "active": true } }, "name": "my-load-balancer-3", "operating_status": "online", "pools": [], "private_ips": [ { "address": "10.0.0.32", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.0.35", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-1231c713-c743-4ff9-b470-b39668c2775e", "id": "0716-1231c713-c743-4ff9-b470-b39668c2775e", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "profile": { "family": "application", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancer/profiles/dynamic", "name": "dynamic" }, "provisioning_status": "active", "public_ips": [ { "address": "192.0.0.56" }, { "address": "192.0.0.44" } ], "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/6eb23aa499254c66917dc265c374eca9", "id": "6eb23aa499254c66917dc265c374eca9", "name": "Default" }, "resource_type": "load_balancer", "route_mode": true, "security_groups": [], "security_groups_supported": false, "source_ip_session_persistence_supported": false, "subnets": [ { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "id": "3ff9fac4-7989-4c2e-ba7a-fad3bbdfaa96", "name": "subnet-1", "resource_type": "subnet" } ], "udp_supported": true }
List all statistics of a load balancer
This request lists statistics of a load balancer.
GET /load_balancers/{id}/statistics
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/statistics?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerStatisticsOptions{} options.SetID(id) statistics, response, err := vpcService.GetLoadBalancerStatistics(options)
GetLoadBalancerStatisticsOptions getLoadBalancerStatisticsOptions = new GetLoadBalancerStatisticsOptions.Builder() .id(id) .build(); Response<LoadBalancerStatistics> response = service.getLoadBalancerStatistics(getLoadBalancerStatisticsOptions).execute(); LoadBalancerStatistics loadBalancerStatistics = response.getResult();
const response = await vpcService.getLoadBalancerStatistics({ id });
response = service.get_load_balancer_statistics(id)
Response
Number of active connections of this load balancer
Example:
797
Current connection rate (connections per second) of this load balancer
Example:
91.121
Total number of data processed (bytes) of this load balancer within current calendar month
Example:
10093173145
Current throughput (Mbps) of this load balancer
Example:
167.278
Status Code
The load balancer statistics were retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "active_connections": 1, "connection_rate": 0, "data_processed_this_month": 2048683, "throughput": 0 }
List all listeners for a load balancer
This request lists all listeners for a load balancer.
GET /load_balancers/{load_balancer_id}/listeners
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancerListenersOptions{} options.SetLoadBalancerID(id) listeners, response, err := vpcService.ListLoadBalancerListeners(options)
ListLoadBalancerListenersOptions listLoadBalancerListenersOptions = new ListLoadBalancerListenersOptions.Builder() .loadBalancerId(loadBalancerId) .build(); Response<LoadBalancerListenerCollection> response = service.listLoadBalancerListeners(listLoadBalancerListenersOptions).execute(); LoadBalancerListenerCollection loadBalancerListenerCollection = response.getResult();
const response = await vpcService.listLoadBalancerListeners({ loadBalancerId });
response = service.list_load_balancer_listeners(load_balancer_id)
Response
Collection of listeners
Status Code
The listeners of the load balancer were retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "listeners": [ { "accept_proxy_protocol": false, "connection_limit": 2000, "created_at": "2018-12-18T01:07:46.739378Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "name": "backend-http" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/4968d116-3174-405a-b334-3b8d00432f0d", "id": "4968d116-3174-405a-b334-3b8d00432f0d", "port": 80, "port_max": 80, "port_min": 80, "protocol": "http", "provisioning_status": "active" }, { "accept_proxy_protocol": false, "connection_limit": 3000, "created_at": "2018-12-18T01:07:46.744224Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988", "id": "54ad563a-0261-11e9-8317-bec54e704988", "name": "backend-tcp" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/d2b9b86e-5704-4b0f-a903-46f63be0addc", "id": "d2b9b86e-5704-4b0f-a903-46f63be0addc", "port": 9000, "port_max": 9000, "port_min": 9000, "protocol": "tcp", "provisioning_status": "active" }, { "accept_proxy_protocol": false, "certificate_instance": { "crn": "crn:[...]" }, "connection_limit": 5000, "created_at": "2018-12-18T01:07:47.808361Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "name": "backend-http" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/30d893b8-1d5a-4bfb-8297-442c6c2f425b", "id": "30d893b8-1d5a-4bfb-8297-442c6c2f425b", "port": 443, "port_max": 443, "port_min": 443, "protocol": "https", "provisioning_status": "active" } ] }
Create a listener for a load balancer
This request creates a new listener for a load balancer.
POST /load_balancers/{load_balancer_id}/listeners
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer listener prototype object
The listener protocol. Each listener in the load balancer must have a unique
port
andprotocol
combination.Load balancers in the
network
family supporttcp
andudp
(ifudp_supported
istrue
). Load balancers in theapplication
family supporttcp
,http
andhttps
.Additional restrictions:
- If
default_pool
is set, the pool's protocol must match, or be compatible with the listener's protocol. At present, the compatible protocols arehttp
andhttps
. - If
https_redirect
is set, the protocol must behttp
.
Allowable values: [
http
,https
,tcp
,udp
]- If
If set to
true
, this listener will accept and forward PROXY protocol information. Supported by load balancers in theapplication
family (otherwise alwaysfalse
). Additional restrictions:- If this listener has
https_redirect
specified, itsaccept_proxy_protocol
value must match theaccept_proxy_protocol
value of thehttps_redirect
listener. - If this listener is the target of another listener's
https_redirect
, itsaccept_proxy_protocol
value must match that listener'saccept_proxy_protocol
value.
Default:
false
Example:
true
- If this listener has
The certificate instance to use for SSL termination. The listener must have a
protocol
ofhttps
.Examples:ViewThe CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate_instance
The connection limit of the listener.
Possible values: 1 ≤ value ≤ 15000
Default:
15000
Example:
2000
The default pool for this listener. If
https_redirect
is specified, the default pool will not be used. If specified, the pool must:- Belong to this load balancer.
- Have the same
protocol
as this listener, or have a compatible protocol. At present, the compatible protocols arehttp
andhttps
. - Not already be the
default_pool
for another listener.
If unspecified, this listener will be created with no default pool, but one may be subsequently set.
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
default_pool
The target listener that requests will be redirected to if none of the listener's
policies
match.If specified, this listener must have a
protocol
ofhttp
, and the target listener must have aprotocol
ofhttps
.The HTTP status code for this redirect.
Allowable values: [
301
,302
,303
,307
,308
]Identifies a load balancer listener by a unique property.
The redirect relative target URI.
Example:
/example?doc=get
https_redirect
The idle connection timeout of the listener in seconds. Supported for load balancers in the
application
family.Possible values: 50 ≤ value ≤ 7200
Default:
50
Example:
100
The policy prototype objects for this listener. The load balancer must be in the
application
family.The listener port number, or the inclusive lower bound of the port range. Each listener in the load balancer must have a unique
port
andprotocol
combination.Not supported for load balancers operating with route mode enabled.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The inclusive upper bound of the range of ports used by this listener. Must not be less than
port_min
.At present, only load balancers operating with route mode enabled, and public load balancers in the
network
family support different values forport_min
andport_max
. When route mode is enabled, the value65535
must be specified.The specified port range must not overlap with port ranges used by other listeners for this load balancer using the same protocol.
Possible values: 1 ≤ value ≤ 65535
Example:
499
The inclusive lower bound of the range of ports used by this listener. Must not be greater than
port_max
.At present, only load balancers operating with route mode enabled, and public load balancers in the
network
family support different values forport_min
andport_max
. When route mode is enabled, the value1
must be specified.The specified port range must not overlap with port ranges used by other listeners for this load balancer using the same protocol.
Possible values: 1 ≤ value ≤ 65535
Example:
443
curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.CreateLoadBalancerListenerOptions{} options.SetLoadBalancerID(lbID) options.SetPort(5656) options.SetProtocol("http") listener, response, err := vpcService.CreateLoadBalancerListener(options)
CreateLoadBalancerListenerOptions createLoadBalancerListenerOptions = new CreateLoadBalancerListenerOptions.Builder() .loadBalancerId(loadBalancerId) .port(Long.valueOf("443")) .protocol("http") .build(); Response<LoadBalancerListener> response = service.createLoadBalancerListener(createLoadBalancerListenerOptions).execute(); LoadBalancerListener loadBalancerListener = response.getResult();
const params = { loadBalancerId, port: 443, protocol: 'http', }; const response = await vpcService.createLoadBalancerListener(params);
certificate_instance_identity_model = {} certificate_instance_identity_model['crn'] = certificate_crn load_balancer_pool_identity_model = {} load_balancer_pool_identity_model['id'] = load_balancer_pool_id load_balancer_listener_policy_prototype_target_model = {} load_balancer_listener_policy_prototype_target_model['id'] = target_id load_balancer_listener_policy_rule_prototype_model = {} load_balancer_listener_policy_rule_prototype_model[ 'condition'] = 'contains' load_balancer_listener_policy_rule_prototype_model[ 'field'] = 'MY-APP-HEADER' load_balancer_listener_policy_rule_prototype_model['type'] = 'header' load_balancer_listener_policy_rule_prototype_model[ 'value'] = 'testString' load_balancer_listener_policy_prototype_model = {} load_balancer_listener_policy_prototype_model['action'] = 'forward' load_balancer_listener_policy_prototype_model['name'] = 'my-policy' load_balancer_listener_policy_prototype_model['priority'] = 5 load_balancer_listener_policy_prototype_model['rules'] = [ load_balancer_listener_policy_rule_prototype_model ] load_balancer_listener_policy_prototype_model[ 'target'] = load_balancer_listener_policy_prototype_target_model port = 443 protocol = 'http' certificate_instance = certificate_instance_identity_model connection_limit = 2000 default_pool = load_balancer_pool_identity_model policies = [load_balancer_listener_policy_prototype_model] response = service.create_load_balancer_listener( load_balancer_id, port, protocol, certificate_instance=certificate_instance, connection_limit=connection_limit, default_pool=default_pool, policies=policies, )
Response
If set to
true
, this listener will accept and forward PROXY protocol information. Supported by load balancers in theapplication
family (otherwise alwaysfalse
). Additional restrictions:- If this listener has
https_redirect
specified, itsaccept_proxy_protocol
value must match theaccept_proxy_protocol
value of thehttps_redirect
listener. - If this listener is the target of another listener's
https_redirect
, itsaccept_proxy_protocol
value must match that listener'saccept_proxy_protocol
value.
Example:
true
- If this listener has
The connection limit of the listener.
Possible values: 1 ≤ value ≤ 15000
Example:
2000
The date and time that this listener was created
The listener's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer listener
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The listener port number, or the inclusive lower bound of the port range.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The inclusive upper bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
499
The inclusive lower bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
443
The listener protocol.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this listener
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The certificate instance used for SSL termination.
If absent, this listener is not using a certificate instance.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate_instance
The default pool for this listener. If absent, this listener has no default pool.
If
https_redirect
is set, the default pool will not be used.The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_pool
If present, the target listener that requests are redirected to if none of the listener's
policies
match.The HTTP status code for this redirect.
Possible values: [
301
,302
,303
,307
,308
]The redirect relative target URI.
Example:
/example?doc=get
https_redirect
The idle connection timeout of the listener in seconds. This property will be present for load balancers in the
application
family.Possible values: 50 ≤ value ≤ 7200
Example:
100
The policies for this listener.
Status Code
The listener was created successfully.
An invalid listener prototype object was provided.
A load balancer with the specified identifier could not be found.
{ "accept_proxy_protocol": false, "connection_limit": 2000, "created_at": "2018-12-18T05:56:05.963323505Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "name": "backend-http" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "id": "f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "port": 80, "port_max": 80, "port_min": 80, "protocol": "http", "provisioning_status": "create_pending" }
Delete a load balancer listener
This request deletes a load balancer listener. This operation cannot be reversed. For this operation to succeed, the listener must not be the target of another load balancer listener.
DELETE /load_balancers/{load_balancer_id}/listeners/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteLoadBalancerListenerOptions{} options.SetLoadBalancerID(lbID) options.SetID(listenerID) response, err := vpcService.DeleteLoadBalancerListener(options)
DeleteLoadBalancerListenerOptions deleteLoadBalancerListenerOptions = new DeleteLoadBalancerListenerOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .build(); Response<Void> response = service.deleteLoadBalancerListener(deleteLoadBalancerListenerOptions).execute();
const response = await vpcService.deleteLoadBalancerListener({ loadBalancerId, id, });
response = service.delete_load_balancer_listener(load_balancer_id, id)
Retrieve a load balancer listener
This request retrieves a single listener specified by the identifier in the URL path.
GET /load_balancers/{load_balancer_id}/listeners/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerListenerOptions{} options.SetLoadBalancerID(lbID) options.SetID(listenerID) listener, response, err := vpcService.GetLoadBalancerListener(options)
GetLoadBalancerListenerOptions getLoadBalancerListenerOptions = new GetLoadBalancerListenerOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .build(); Response<LoadBalancerListener> response = service.getLoadBalancerListener(getLoadBalancerListenerOptions).execute(); LoadBalancerListener loadBalancerListener = response.getResult();
const response = await vpcService.getLoadBalancerListener({ loadBalancerId, id, });
response = service.get_load_balancer_listener(load_balancer_id, id)
Response
If set to
true
, this listener will accept and forward PROXY protocol information. Supported by load balancers in theapplication
family (otherwise alwaysfalse
). Additional restrictions:- If this listener has
https_redirect
specified, itsaccept_proxy_protocol
value must match theaccept_proxy_protocol
value of thehttps_redirect
listener. - If this listener is the target of another listener's
https_redirect
, itsaccept_proxy_protocol
value must match that listener'saccept_proxy_protocol
value.
Example:
true
- If this listener has
The connection limit of the listener.
Possible values: 1 ≤ value ≤ 15000
Example:
2000
The date and time that this listener was created
The listener's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer listener
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The listener port number, or the inclusive lower bound of the port range.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The inclusive upper bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
499
The inclusive lower bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
443
The listener protocol.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this listener
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The certificate instance used for SSL termination.
If absent, this listener is not using a certificate instance.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate_instance
The default pool for this listener. If absent, this listener has no default pool.
If
https_redirect
is set, the default pool will not be used.The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_pool
If present, the target listener that requests are redirected to if none of the listener's
policies
match.The HTTP status code for this redirect.
Possible values: [
301
,302
,303
,307
,308
]The redirect relative target URI.
Example:
/example?doc=get
https_redirect
The idle connection timeout of the listener in seconds. This property will be present for load balancers in the
application
family.Possible values: 50 ≤ value ≤ 7200
Example:
100
The policies for this listener.
Status Code
The listener was retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "accept_proxy_protocol": false, "connection_limit": 2000, "created_at": "2018-12-18T05:56:05.963323505Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "name": "backend-http" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "id": "f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "port": 80, "port_max": 80, "port_min": 80, "protocol": "http", "provisioning_status": "active" }
Update a load balancer listener
This request updates a load balancer listener from a listener patch.
PATCH /load_balancers/{load_balancer_id}/listeners/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer listener patch
If set to
true
, this listener will accept and forward PROXY protocol information. Supported by load balancers in theapplication
family (otherwise alwaysfalse
). Additional restrictions:- If this listener has
https_redirect
specified, itsaccept_proxy_protocol
value must match theaccept_proxy_protocol
value of thehttps_redirect
listener. - If this listener is the target of another listener's
https_redirect
, itsaccept_proxy_protocol
value must match that listener'saccept_proxy_protocol
value.
Example:
true
- If this listener has
The certificate instance to use for SSL termination. The listener must have a
protocol
ofhttps
.Examples:ViewThe CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate_instance
The connection limit of the listener.
Possible values: 1 ≤ value ≤ 15000
Example:
2000
The default pool for this listener. If
https_redirect
is set, the default pool will not be used. The specified pool must:- Belong to this load balancer
- Have the same
protocol
as this listener, or have a compatible protocol. At present, the compatible protocols arehttp
andhttps
. - Not already be the
default_pool
for another listener
Specify
null
to remove an existing default pool.The target listener that requests will be redirected to if none of the listener's
policies
match.If specified, this listener must have a
protocol
ofhttp
, and the target listener must have aprotocol
ofhttps
.Specify
null
to remove any existing https redirect.The HTTP status code for this redirect.
Allowable values: [
301
,302
,303
,307
,308
]Identifies a load balancer listener by a unique property.
The redirect relative target URI.
Example:
/example?doc=get
https_redirect
The idle connection timeout of the listener in seconds. Supported for load balancers in the
application
family.Possible values: 50 ≤ value ≤ 7200
Example:
100
The listener port number, or the inclusive lower bound of the port range. Each listener in the load balancer must have a unique
port
andprotocol
combination.Not supported for load balancers operating with route mode enabled.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The inclusive upper bound of the range of ports used by this listener. Must not be less than
port_min
.At present, only load balancers operating with route mode enabled, and public load balancers in the
network
family support different values forport_min
andport_max
. When route mode is enabled, the value65535
must be specified.The specified port range must not overlap with port ranges used by other listeners for this load balancer using the same protocol.
Possible values: 1 ≤ value ≤ 65535
Example:
499
The inclusive lower bound of the range of ports used by this listener. Must not be greater than
port_max
.At present, only load balancers operating with route mode enabled, and public load balancers in the
network
family support different values forport_min
andport_max
. When route mode is enabled, the value1
must be specified.The specified port range must not overlap with port ranges used by other listeners for this load balancer using the same protocol.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The listener protocol. Each listener in the load balancer must have a unique
port
andprotocol
combination.Load balancers in the
network
family supporttcp
andudp
(ifudp_supported
istrue
). Load balancers in theapplication
family supporttcp
,http
andhttps
.Additional restrictions:
- If
default_pool
is set, the protocol cannot be changed. - If
https_redirect
is set, the protocol must behttp
. - If another listener's
https_redirect
targets this listener, the protocol must behttps
.
Allowable values: [
http
,https
,tcp
,udp
]- If
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "port": 80 }'
options := &vpcv1.UpdateLoadBalancerListenerOptions{} options.SetLoadBalancerID(lbID) options.SetID(listenerID) options.SetProtocol("tcp") listener, response, err := vpcService.UpdateLoadBalancerListener(options)
UpdateLoadBalancerListenerOptions updateLoadBalancerListenerOptions = new UpdateLoadBalancerListenerOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .name(name) .build(); Response<LoadBalancerListener> response = service.updateLoadBalancerListener(updateLoadBalancerListenerOptions).execute(); LoadBalancerListener loadBalancerListener = response.getResult();
const response = await vpcService.updateLoadBalancerListener({ loadBalancerId, id, port: 443, protocol: 'http', });
certificate_instance_identity_model = {} certificate_instance_identity_model['crn'] = certificate_id load_balancer_pool_identity_model = {} load_balancer_pool_identity_model['id'] = load_balancer_pool_id certificate_instance = certificate_instance_identity_model connection_limit = 2500 default_pool = load_balancer_pool_identity_model port = 443 protocol = 'http' response = service.update_load_balancer_listener( load_balancer_id, id, certificate_instance=certificate_instance, connection_limit=connection_limit, default_pool=default_pool, port=port, protocol=protocol, )
Response
If set to
true
, this listener will accept and forward PROXY protocol information. Supported by load balancers in theapplication
family (otherwise alwaysfalse
). Additional restrictions:- If this listener has
https_redirect
specified, itsaccept_proxy_protocol
value must match theaccept_proxy_protocol
value of thehttps_redirect
listener. - If this listener is the target of another listener's
https_redirect
, itsaccept_proxy_protocol
value must match that listener'saccept_proxy_protocol
value.
Example:
true
- If this listener has
The connection limit of the listener.
Possible values: 1 ≤ value ≤ 15000
Example:
2000
The date and time that this listener was created
The listener's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer listener
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The listener port number, or the inclusive lower bound of the port range.
Possible values: 1 ≤ value ≤ 65535
Example:
443
The inclusive upper bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
499
The inclusive lower bound of the range of ports used by this listener.
At present, only load balancers in the
network
family support more than one port per listener.Possible values: 1 ≤ value ≤ 65535
Example:
443
The listener protocol.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this listener
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The certificate instance used for SSL termination.
If absent, this listener is not using a certificate instance.
The CRN for this certificate instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:secrets-manager:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34:36fa422d-080d-4d83-8d2d-86851b4001df:secret:2e786aab-42fa-63ed-14f8-d66d552f4dd5
certificate_instance
The default pool for this listener. If absent, this listener has no default pool.
If
https_redirect
is set, the default pool will not be used.The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer-pool
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
default_pool
If present, the target listener that requests are redirected to if none of the listener's
policies
match.The HTTP status code for this redirect.
Possible values: [
301
,302
,303
,307
,308
]The redirect relative target URI.
Example:
/example?doc=get
https_redirect
The idle connection timeout of the listener in seconds. This property will be present for load balancers in the
application
family.Possible values: 50 ≤ value ≤ 7200
Example:
100
The policies for this listener.
Status Code
The listener update request was accepted.
An invalid listener patch was provided.
A listener with the specified identifier could not be found.
{ "accept_proxy_protocol": false, "connection_limit": 2000, "created_at": "2018-12-18T05:56:05.963323505Z", "default_pool": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "name": "backend-http" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/listeners/f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "id": "f5ceb28b-f448-4a5e-8d9d-ec81714f20bd", "port": 80, "port_max": 80, "port_min": 80, "protocol": "http", "provisioning_status": "update_pending" }
List all policies for a load balancer listener
This request lists all policies for a load balancer listener. A policy consists of rules to match against each incoming request, and an action to apply to the request if a rule matches.
GET /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies
Request
Path Parameters
The load balancer identifier
The listener identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancerListenerPoliciesOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) policies, response, err := vpcService.ListLoadBalancerListenerPolicies(options)
ListLoadBalancerListenerPoliciesOptions listLoadBalancerListenerPoliciesOptions = new ListLoadBalancerListenerPoliciesOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .build(); Response<LoadBalancerListenerPolicyCollection> response = service.listLoadBalancerListenerPolicies(listLoadBalancerListenerPoliciesOptions).execute(); LoadBalancerListenerPolicyCollection loadBalancerListenerPolicyCollection = response.getResult();
const response = await vpcService.listLoadBalancerListenerPolicies({ loadBalancerId, listenerId, });
response = service.list_load_balancer_listener_policies( load_balancer_id, listener_id)
Create a policy for a load balancer listener
This request creates a new policy from a load balancer listener policy object. The prototype
object is structured in the same way as a retrieved policy, and contains the information
necessary to create the new policy. For this request to succeed, the listener must have
a protocol
of http
or https
.
POST /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies
Request
Path Parameters
The load balancer identifier
The listener identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The listener policy prototype object
The policy action.
forward
: Requests will be forwarded to the specifiedtarget
poolhttps_redirect
: Requests will be redirected to the specified target listener. The listener must have aprotocol
ofhttp
, and the target listener must have aprotocol
ofhttps
redirect
: Requests will be redirected to the specifiedtarget.url
reject
: Requests will be rejected with a403
status code
The enumerated values for this property may expand in the future.
Allowable values: [
forward
,https_redirect
,redirect
,reject
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Priority of the policy. The priority is unique across all policies for this load balancer listener. Lower value indicates higher priority.
Possible values: 1 ≤ value ≤ 10
Example:
5
The name for this policy. The name must not be used by another policy for the load balancer listener. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-policy
The rule prototype objects for this policy.
- If
action
isforward
, specify aLoadBalancerPoolIdentity
. - If
action
ishttps_redirect
, specify aLoadBalancerListenerPolicyHTTPSRedirectPrototype
. - If
action
isredirect
, specify aLoadBalancerListenerPolicyRedirectURLPrototype
.
- If
curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "action": "reject", "priority": 1, "rules": [ { "type": "header", "value": "my-value", "condition": "contains", "field": "MY-APP-HEADER" } ] }'
options := &vpcv1.CreateLoadBalancerListenerPolicyOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPriority(2) options.SetAction("reject") policy, response, err := vpcService.CreateLoadBalancerListenerPolicy(options)
CreateLoadBalancerListenerPolicyOptions createLoadBalancerListenerPolicyOptions = new CreateLoadBalancerListenerPolicyOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .priority(Long.valueOf("5")) .action("forward") .build(); Response<LoadBalancerListenerPolicy> response = service.createLoadBalancerListenerPolicy(createLoadBalancerListenerPolicyOptions).execute(); LoadBalancerListenerPolicy loadBalancerListenerPolicy = response.getResult();
const params = { loadBalancerId, listenerId, priority: 5, action: 'forward', name: 'my-load-balancer-listener-policy', }; const response = await vpcService.createLoadBalancerListenerPolicy(params);
load_balancer_listener_policy_rule_prototype_model = {} load_balancer_listener_policy_rule_prototype_model['condition'] = 'contains' load_balancer_listener_policy_rule_prototype_model['field'] = 'MY-APP-HEADER' load_balancer_listener_policy_rule_prototype_model['type'] = 'header' load_balancer_listener_policy_rule_prototype_model['value'] = 'testString' load_balancer_listener_policy_prototype_target_model = {} load_balancer_listener_policy_prototype_target_model['id'] = target_id action = 'forward' priority = 5 name = 'my-listener-policy' rules = [load_balancer_listener_policy_rule_prototype_model] target = load_balancer_listener_policy_prototype_target_model response = service.create_load_balancer_listener_policy( load_balancer_id, listener_id, action, priority, name=name, rules=rules, target=target, )
Response
The policy action.
forward
: Requests will be forwarded to the specifiedtarget
poolhttps_redirect
: Requests will be redirected to the specified target listener. The listener must have aprotocol
ofhttp
, and the target listener must have aprotocol
ofhttps
redirect
: Requests will be redirected to the specifiedtarget.url
reject
: Requests will be rejected with a403
status code
The enumerated values for this property may expand in the future.
Possible values: [
forward
,https_redirect
,redirect
,reject
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that this policy was created
The listener policy's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278
The policy's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer listener policy. The name is unique across all policies for the load balancer listener.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-policy
Priority of the policy. The priority is unique across all policies for this load balancer listener. Lower value indicates higher priority.
Possible values: 1 ≤ value ≤ 10
Example:
5
The provisioning status of this policy
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The rules for this policy.
- If
action
isforward
, the response is aLoadBalancerPoolReference
- If
action
ishttps_redirect
, the response is aLoadBalancerListenerPolicyHTTPSRedirect
- If
action
isredirect
, the response is aLoadBalancerListenerPolicyRedirectURL
- If
Status Code
The policy was created successfully.
An invalid listener policy prototype object was provided.
A load balancer or listener with the specified identifier could not be found.
No Sample Response
Delete a load balancer listener policy
Deletes a policy of the load balancer listener. This operation cannot be reversed.
DELETE /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteLoadBalancerListenerPolicyOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetID(policyID) response, err := vpcService.DeleteLoadBalancerListenerPolicy(options)
DeleteLoadBalancerListenerPolicyOptions deleteLoadBalancerListenerPolicyOptions = new DeleteLoadBalancerListenerPolicyOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .id(id) .build(); Response<Void> response = service.deleteLoadBalancerListenerPolicy(deleteLoadBalancerListenerPolicyOptions).execute();
const response = await vpcService.deleteLoadBalancerListenerPolicy({ loadBalancerId, listenerId, id, });
response = service.delete_load_balancer_listener_policy( load_balancer_id, listener_id, id)
Retrieve a load balancer listener policy
Retrieve a single policy specified by the identifier in the URL path.
GET /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerListenerPolicyOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetID(policyID) policy, response, err := vpcService.GetLoadBalancerListenerPolicy(options)
GetLoadBalancerListenerPolicyOptions getLoadBalancerListenerPolicyOptions = new GetLoadBalancerListenerPolicyOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .id(id) .build(); Response<LoadBalancerListenerPolicy> response = service.getLoadBalancerListenerPolicy(getLoadBalancerListenerPolicyOptions).execute(); LoadBalancerListenerPolicy loadBalancerListenerPolicy = response.getResult();
const response = await vpcService.getLoadBalancerListenerPolicy({ loadBalancerId, listenerId, id, });
response = service.get_load_balancer_listener_policy( load_balancer_id, listener_id, id)
Response
The policy action.
forward
: Requests will be forwarded to the specifiedtarget
poolhttps_redirect
: Requests will be redirected to the specified target listener. The listener must have aprotocol
ofhttp
, and the target listener must have aprotocol
ofhttps
redirect
: Requests will be redirected to the specifiedtarget.url
reject
: Requests will be rejected with a403
status code
The enumerated values for this property may expand in the future.
Possible values: [
forward
,https_redirect
,redirect
,reject
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that this policy was created
The listener policy's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278
The policy's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer listener policy. The name is unique across all policies for the load balancer listener.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-policy
Priority of the policy. The priority is unique across all policies for this load balancer listener. Lower value indicates higher priority.
Possible values: 1 ≤ value ≤ 10
Example:
5
The provisioning status of this policy
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The rules for this policy.
- If
action
isforward
, the response is aLoadBalancerPoolReference
- If
action
ishttps_redirect
, the response is aLoadBalancerListenerPolicyHTTPSRedirect
- If
action
isredirect
, the response is aLoadBalancerListenerPolicyRedirectURL
- If
Status Code
The policy was retrieved successfully.
A load balancer or listener with the specified identifier could not be found.
No Sample Response
Update a load balancer listener policy
This request updates a load balancer listener policy with the information in a provided policy patch. The policy patch object is structured in the same way as a retrieved policy and contains only the information to be updated.
PATCH /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The listener policy patch
The name for this policy. The name must not be used by another policy for the load balancer listener.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-policy
Priority of the policy. The priority is unique across all policies for this load balancer listener. Lower value indicates higher priority.
Possible values: 1 ≤ value ≤ 10
Example:
5
- If
action
isforward
, specify aLoadBalancerPoolIdentity
. - If
action
ishttps_redirect
, specify aLoadBalancerListenerPolicyHTTPSRedirectPatch
. - If
action
isredirect
, specify aLoadBalancerListenerPolicyRedirectURLPatch
.
- If
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "priority": 5 }'
options := &vpcv1.UpdateLoadBalancerListenerPolicyOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetID(policyID) options.SetPriority(4) options.SetName("my-policy") target := &vpcv1.LoadBalancerListenerPolicyPatchTarget{ ID: &targetPoolID, } options.SetTarget(target) policy, response, err := vpcService.UpdateLoadBalancerListenerPolicy(options)
UpdateLoadBalancerListenerPolicyOptions updateLoadBalancerListenerPolicyOptions = new UpdateLoadBalancerListenerPolicyOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .id(id) .name(name) .build(); Response<LoadBalancerListenerPolicy> response = service.updateLoadBalancerListenerPolicy(updateLoadBalancerListenerPolicyOptions).execute(); LoadBalancerListenerPolicy loadBalancerListenerPolicy = response.getResult();
const params = { loadBalancerId, listenerId, id, name: 'my-load-balancer-listener-policy', }; const response = await vpcService.updateLoadBalancerListenerPolicy(params);
load_balancer_listener_policy_patch_target_model = {} load_balancer_listener_policy_patch_target_model['id'] = target_id name = 'my-listener-policy' priority = 6 target = load_balancer_listener_policy_patch_target_model response = service.update_load_balancer_listener_policy( load_balancer_id, listener_id, id, name=name, priority=priority, target=target, )
Response
The policy action.
forward
: Requests will be forwarded to the specifiedtarget
poolhttps_redirect
: Requests will be redirected to the specified target listener. The listener must have aprotocol
ofhttp
, and the target listener must have aprotocol
ofhttps
redirect
: Requests will be redirected to the specifiedtarget.url
reject
: Requests will be rejected with a403
status code
The enumerated values for this property may expand in the future.
Possible values: [
forward
,https_redirect
,redirect
,reject
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that this policy was created
The listener policy's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278
The policy's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer listener policy. The name is unique across all policies for the load balancer listener.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-policy
Priority of the policy. The priority is unique across all policies for this load balancer listener. Lower value indicates higher priority.
Possible values: 1 ≤ value ≤ 10
Example:
5
The provisioning status of this policy
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The rules for this policy.
- If
action
isforward
, the response is aLoadBalancerPoolReference
- If
action
ishttps_redirect
, the response is aLoadBalancerListenerPolicyHTTPSRedirect
- If
action
isredirect
, the response is aLoadBalancerListenerPolicyRedirectURL
- If
Status Code
The policy update request was accepted.
An invalid listener policy patch was provided.
A load balancer or listener with the specified identifier could not be found.
No Sample Response
List all rules of a load balancer listener policy
This request lists all rules of a load balancer listener policy.
GET /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{policy_id}/rules
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancerListenerPolicyRulesOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPolicyID(policyID) rules, response, err := vpcService.ListLoadBalancerListenerPolicyRules(options)
ListLoadBalancerListenerPolicyRulesOptions listLoadBalancerListenerPolicyRulesOptions = new ListLoadBalancerListenerPolicyRulesOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .policyId(policyId) .build(); Response<LoadBalancerListenerPolicyRuleCollection> response = service.listLoadBalancerListenerPolicyRules(listLoadBalancerListenerPolicyRulesOptions).execute(); LoadBalancerListenerPolicyRuleCollection loadBalancerListenerPolicyRuleCollection = response.getResult();
const response = await vpcService.listLoadBalancerListenerPolicyRules({ loadBalancerId, listenerId, policyId, });
response = service.list_load_balancer_listener_policy_rules( load_balancer_id, listener_id, policy_id)
Create a rule for a load balancer listener policy
Creates a new rule for the load balancer listener policy.
POST /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{policy_id}/rules
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The listener policy rule prototype object
The condition of the rule.
Allowable values: [
contains
,equals
,matches_regex
]The type of the rule.
Body rules are applied to form-encoded request bodies using the
UTF-8
character set.Allowable values: [
body
,header
,hostname
,path
,query
]Value to be matched for rule condition.
If the rule type is
query
and the rule condition is notmatches_regex
, the value must be percent-encoded.Possible values: 1 ≤ length ≤ 128
The field. This is applicable to
header
,query
, andbody
rule types.If the rule type is
header
, this property is required.If the rule type is
query
, this is optional. If specified and the rule condition is notmatches_regex
, the value must be percent-encoded.If the rule type is
body
, this is optional.Possible values: 1 ≤ length ≤ 128
Example:
MY-APP-HEADER
curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "condition": "contains", "field": "MY-APP-HEADER", "type": "header", "value": "my-value" }'
options := &vpcv1.CreateLoadBalancerListenerPolicyRuleOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPolicyID(policyID) options.SetCondition("contains") options.SetType("hostname") options.SetValue("one") rule, response, err := vpcService.CreateLoadBalancerListenerPolicyRule(options)
CreateLoadBalancerListenerPolicyRuleOptions createLoadBalancerListenerPolicyRuleOptions = new CreateLoadBalancerListenerPolicyRuleOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .policyId(policyId) .condition("contains") .type("header") .value("25") .build(); Response<LoadBalancerListenerPolicyRule> response = service.createLoadBalancerListenerPolicyRule(createLoadBalancerListenerPolicyRuleOptions).execute(); LoadBalancerListenerPolicyRule loadBalancerListenerPolicyRule = response.getResult();
const params = { loadBalancerId, listenerId, policyId, condition: 'contains', type: 'header', value, }; const response = await vpcService.createLoadBalancerListenerPolicyRule(params);
condition = 'contains' type = 'header' value = 'test' field = 'MY-APP-HEADER' response = service.create_load_balancer_listener_policy_rule( load_balancer_id, listener_id, policy_id, condition, type, value, field=field, )
Response
The condition of the rule.
Possible values: [
contains
,equals
,matches_regex
]The date and time that this rule was created
The rule's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278/rules/873a84b0-84d6-49c6-8948-1fa527b25762
The rule's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The provisioning status of this rule
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The type of the rule.
Body rules are applied to form-encoded request bodies using the
UTF-8
character set.Possible values: [
body
,header
,hostname
,path
,query
]Value to be matched for rule condition.
If the rule type is
query
and the rule condition is notmatches_regex
, the value must be percent-encoded.Possible values: 1 ≤ length ≤ 128
The field. This is applicable to
header
,query
, andbody
rule types.If the rule type is
header
, this property is required.If the rule type is
query
, this is optional. If specified and the rule condition is notmatches_regex
, the value must be percent-encoded.If the rule type is
body
, this is optional.Possible values: 1 ≤ length ≤ 128
Example:
MY-APP-HEADER
Status Code
The rule was created successfully.
An invalid rule prototype object was provided.
A load balancer, listener, or policy with the specified identifier could not be found.
No Sample Response
Delete a load balancer listener policy rule
Deletes a rule from the load balancer listener policy. This operation cannot be reversed.
DELETE /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{policy_id}/rules/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules/$rule_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteLoadBalancerListenerPolicyRuleOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPolicyID(policyID) options.SetID(ruleID) response, err := vpcService.DeleteLoadBalancerListenerPolicyRule(options)
DeleteLoadBalancerListenerPolicyRuleOptions deleteLoadBalancerListenerPolicyRuleOptions = new DeleteLoadBalancerListenerPolicyRuleOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .policyId(policyId) .id(id) .build(); Response<Void> response = service.deleteLoadBalancerListenerPolicyRule(deleteLoadBalancerListenerPolicyRuleOptions).execute();
const response = await vpcService.deleteLoadBalancerListenerPolicyRule({ loadBalancerId, listenerId, policyId, id, });
response = service.delete_load_balancer_listener_policy_rule( load_balancer_id, listener_id, policy_id, id)
Retrieve a load balancer listener policy rule
Retrieves a single rule specified by the identifier in the URL path.
GET /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{policy_id}/rules/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules/$rule_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerListenerPolicyRuleOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPolicyID(policyID) options.SetID(ruleID) rule, response, err := vpcService.GetLoadBalancerListenerPolicyRule(options)
GetLoadBalancerListenerPolicyRuleOptions getLoadBalancerListenerPolicyRuleOptions = new GetLoadBalancerListenerPolicyRuleOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .policyId(policyId) .id(id) .build(); Response<LoadBalancerListenerPolicyRule> response = service.getLoadBalancerListenerPolicyRule(getLoadBalancerListenerPolicyRuleOptions).execute(); LoadBalancerListenerPolicyRule loadBalancerListenerPolicyRule = response.getResult();
const response = await vpcService.getLoadBalancerListenerPolicyRule({ loadBalancerId, listenerId, policyId, id, });
response = service.get_load_balancer_listener_policy_rule( load_balancer_id, listener_id, policy_id, id)
Response
The condition of the rule.
Possible values: [
contains
,equals
,matches_regex
]The date and time that this rule was created
The rule's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278/rules/873a84b0-84d6-49c6-8948-1fa527b25762
The rule's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The provisioning status of this rule
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The type of the rule.
Body rules are applied to form-encoded request bodies using the
UTF-8
character set.Possible values: [
body
,header
,hostname
,path
,query
]Value to be matched for rule condition.
If the rule type is
query
and the rule condition is notmatches_regex
, the value must be percent-encoded.Possible values: 1 ≤ length ≤ 128
The field. This is applicable to
header
,query
, andbody
rule types.If the rule type is
header
, this property is required.If the rule type is
query
, this is optional. If specified and the rule condition is notmatches_regex
, the value must be percent-encoded.If the rule type is
body
, this is optional.Possible values: 1 ≤ length ≤ 128
Example:
MY-APP-HEADER
Status Code
The rule was retrieved successfully.
A load balancer, listener or policy with the specified identifier could not be found.
No Sample Response
Update a load balancer listener policy rule
Updates a rule of the load balancer listener policy.
PATCH /load_balancers/{load_balancer_id}/listeners/{listener_id}/policies/{policy_id}/rules/{id}
Request
Path Parameters
The load balancer identifier
The listener identifier
The policy identifier
The rule identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The listener policy rule patch.
The condition of the rule.
Allowable values: [
contains
,equals
,matches_regex
]The field. This is applicable to
header
,query
, andbody
rule types.If the rule type is
header
, this property is required.If the rule type is
query
, this is optional. If specified and the rule condition is notmatches_regex
, the value must be percent-encoded.If the rule type is
body
, this is optional.Possible values: 1 ≤ length ≤ 128
Example:
MY-APP-HEADER
The type of the rule.
Body rules are applied to form-encoded request bodies using the
UTF-8
character set.Allowable values: [
body
,header
,hostname
,path
,query
]Value to be matched for rule condition.
If the rule type is
query
and the rule condition is notmatches_regex
, the value must be percent-encoded.Possible values: 1 ≤ length ≤ 128
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules/$rule_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "value": "my-new-value" }'
options := &vpcv1.UpdateLoadBalancerListenerPolicyRuleOptions{} options.SetLoadBalancerID(lbID) options.SetListenerID(listenerID) options.SetPolicyID(policyID) options.SetID(ruleID) options.SetCondition("equals") options.SetType("header") options.SetValue("1") options.SetField("some-name") rule, response, err := vpcService.UpdateLoadBalancerListenerPolicyRule(options)
UpdateLoadBalancerListenerPolicyRuleOptions updateLoadBalancerListenerPolicyRuleOptions = new UpdateLoadBalancerListenerPolicyRuleOptions.Builder() .loadBalancerId(loadBalancerId) .listenerId(listenerId) .policyId(policyId) .id(id) .name(name) .build(); Response<LoadBalancerListenerPolicyRule> response = service.updateLoadBalancerListenerPolicyRule(updateLoadBalancerListenerPolicyRuleOptions).execute(); LoadBalancerListenerPolicyRule loadBalancerListenerPolicyRule = response.getResult();
const params = { loadBalancerId, listenerId, policyId, id, condition: 'contains', type: 'header', }; const response = await vpcService.updateLoadBalancerListenerPolicyRule(params);
condition = 'contains' field = 'MY-APP-HEADER' type = 'header' value = 'testValue' response = service.update_load_balancer_listener_policy_rule( load_balancer_id, listener_id, policy_id, id, condition=condition, field=field, type=type, value=value, )
Response
The condition of the rule.
Possible values: [
contains
,equals
,matches_regex
]The date and time that this rule was created
The rule's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/listeners/70294e14-4e61-11e8-bcf4-0242ac110004/policies/f3187486-7b27-4c79-990c-47d33c0e2278/rules/873a84b0-84d6-49c6-8948-1fa527b25762
The rule's unique identifier.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The provisioning status of this rule
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The type of the rule.
Body rules are applied to form-encoded request bodies using the
UTF-8
character set.Possible values: [
body
,header
,hostname
,path
,query
]Value to be matched for rule condition.
If the rule type is
query
and the rule condition is notmatches_regex
, the value must be percent-encoded.Possible values: 1 ≤ length ≤ 128
The field. This is applicable to
header
,query
, andbody
rule types.If the rule type is
header
, this property is required.If the rule type is
query
, this is optional. If specified and the rule condition is notmatches_regex
, the value must be percent-encoded.If the rule type is
body
, this is optional.Possible values: 1 ≤ length ≤ 128
Example:
MY-APP-HEADER
Status Code
The rule update request was accepted.
An invalid rule patch was provided.
A load balancer, listener or policy with the specified identifier could not be found.
No Sample Response
List all pools of a load balancer
This request lists all pools of a load balancer.
GET /load_balancers/{load_balancer_id}/pools
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancerPoolsOptions{} options.SetLoadBalancerID(id) pools, response, err := vpcService.ListLoadBalancerPools(options)
ListLoadBalancerPoolsOptions listLoadBalancerPoolsOptions = new ListLoadBalancerPoolsOptions.Builder() .loadBalancerId(loadBalancerId) .build(); Response<LoadBalancerPoolCollection> response = service.listLoadBalancerPools(listLoadBalancerPoolsOptions).execute(); LoadBalancerPoolCollection loadBalancerPoolCollection = response.getResult();
const response = await vpcService.listLoadBalancerPools({ id });
response = service.list_load_balancer_pools(load_balancer_id)
Response
Collection of pools
Status Code
The pools of the load balancer were retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "pools": [ { "algorithm": "least_connections", "created_at": "2018-12-18T01:07:46.716159Z", "health_monitor": { "delay": 5, "max_retries": 2, "timeout": 2, "type": "http", "url_path": "/" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988", "id": "54ab4393-0261-11e9-8317-bec54e704988", "members": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988/members/8c4ba2ee-9b24-452c-b720-1f885a20407c", "id": "8c4ba2ee-9b24-452c-b720-1f885a20407c" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ab4393-0261-11e9-8317-bec54e704988/members/32d9ef39-9513-4bc9-a089-8809656b12e5", "id": "32d9ef39-9513-4bc9-a089-8809656b12e5" } ], "name": "backend-http", "protocol": "http", "provisioning_status": "active", "proxy_protocol": "v1", "session_persistence": { "cookie_name": "IBMVPCALB_r134-7013ddb4-4cdd-4f9b-ae3b-ed317d089250", "type": "http_cookie" } }, { "algorithm": "round_robin", "created_at": "2018-12-18T01:07:46.729263Z", "health_monitor": { "delay": 5, "max_retries": 2, "timeout": 2, "type": "http", "url_path": "/" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988", "id": "fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8", "members": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/c8184f3f-3663-41f4-a353-2abb593cd9fe", "id": "c8184f3f-3663-41f4-a353-2abb593cd9fe" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/e0f7d259-e365-41d5-8fe8-fbc8b16341d1", "id": "e0f7d259-e365-41d5-8fe8-fbc8b16341d1" } ], "name": "backend-tcp", "protocol": "tcp", "provisioning_status": "active", "proxy_protocol": "disabled", "session_persistence": { "type": "source_ip" } } ] }
Create a load balancer pool
This request creates a new pool from a pool prototype object.
POST /load_balancers/{load_balancer_id}/pools
Request
Path Parameters
The load balancer identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer pool prototype object.
The load balancing algorithm.
Allowable values: [
least_connections
,round_robin
,weighted_round_robin
]The health monitor of this pool.
The seconds to wait between health checks. Must be greater than
timeout
.Possible values: 2 ≤ value ≤ 60
Example:
5
The health check max retries.
Possible values: 1 ≤ value ≤ 10
Example:
2
The seconds to wait for a response to a health check. Must be less than
delay
.Possible values: 1 ≤ value ≤ 59
Example:
2
The protocol type to use for health checks.
Allowable values: [
http
,https
,tcp
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The health check port.
If specified, this overrides the pool member port values.
Possible values: 1 ≤ value ≤ 65535
Example:
22
The health check URL path. Applicable when
type
ishttp
orhttps
.Must be in the format of an origin-form request target.
Possible values: Value must match regular expression
^\/(([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})+(\/([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})*)*)?(\?([a-zA-Z0-9-._~!$&'()*+,;=:@\/?]|%[a-fA-F0-9]{2})*)?$
Example:
/
health_monitor
The protocol used for this load balancer pool. Load balancers in the
network
family supporttcp
andudp
(ifudp_supported
istrue
). Load balancers in theapplication
family supporttcp
,http
, andhttps
.Allowable values: [
http
,https
,tcp
,udp
]The members for this load balancer pool. For load balancers in the
network
family, the sameport
andtarget
tuple cannot be shared by a pool member of any other load balancer in the same VPC.The name for this load balancer pool. The name must not be used by another pool for the load balancer. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer-pool
The PROXY protocol setting for this pool:
v1
: Enabled with version 1 (human-readable header format)v2
: Enabled with version 2 (binary header format)disabled
: Disabled
Supported by load balancers in the
application
family (otherwise alwaysdisabled
).Allowable values: [
disabled
,v1
,v2
]Default:
disabled
The session persistence of this pool. Only applicable to load balancers that have
source_ip_session_persistence_supported
specified astrue
in the profile. If unspecified, session persistence will be disabled, and traffic will be distributed across backend server members of the pool.The session persistence type. The
http_cookie
andapp_cookie
types are applicable only to thehttp
andhttps
protocols.Allowable values: [
app_cookie
,http_cookie
,source_ip
]The session persistence cookie name. Applicable only for type
app_cookie
. Names starting withIBM
are not allowed.Possible values: Value must match regular expression
^[-A-Za-z0-9!#$%&'*+.^_`~|]+$
Example:
my-cookie-name
session_persistence
curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-pool", "algorithm": "round_robin", "health_monitor": { "delay": 51, "max_retries": 3, "timeout": 21, "type": "http", "url_path": "/" }, "protocol": "http", "session_persistence": { "cookie_name": "my-cookie-name", "type": "app_cookie" } }'
options := &vpcv1.CreateLoadBalancerPoolOptions{} options.SetLoadBalancerID(lbID) options.SetAlgorithm("round_robin") options.SetHealthMonitor(&vpcv1.LoadBalancerPoolHealthMonitorPrototype{ Delay: core.Int64Ptr(5), MaxRetries: core.Int64Ptr(2), Timeout: core.Int64Ptr(4), Type: core.StringPtr("http"), }) options.SetName(name) options.SetProtocol("http") pool, response, err := vpcService.CreateLoadBalancerPool(options)
LoadBalancerPoolHealthMonitorPrototype loadBalancerPoolHealthMonitorPrototypeModel = new LoadBalancerPoolHealthMonitorPrototype.Builder() .delay(Long.valueOf("5")) .maxRetries(Long.valueOf("2")) .timeout(Long.valueOf("2")) .type("http") .build(); CreateLoadBalancerPoolOptions createLoadBalancerPoolOptions = new CreateLoadBalancerPoolOptions.Builder() .loadBalancerId(loadBalancerId) .algorithm("least_connections") .protocol("http") .healthMonitor(loadBalancerPoolHealthMonitorPrototypeModel) .build(); Response<LoadBalancerPool> response = service.createLoadBalancerPool(createLoadBalancerPoolOptions).execute(); LoadBalancerPool loadBalancerPool = response.getResult();
const loadBalancerPoolHealthMonitorPrototypeModel = { delay: 5, max_retries: 2, port: 22, timeout: 2, type: 'http', url_path: '/', }; const params = { loadBalancerId, name: 'my-load-balancer-pool', algorithm: 'least_connections', protocol: 'http', healthMonitor: loadBalancerPoolHealthMonitorPrototypeModel, }; const response = await vpcService.createLoadBalancerPool(params);
load_balancer_pool_health_monitor_prototype_model = {} load_balancer_pool_health_monitor_prototype_model['delay'] = 5 load_balancer_pool_health_monitor_prototype_model['max_retries'] = 2 load_balancer_pool_health_monitor_prototype_model['port'] = 22 load_balancer_pool_health_monitor_prototype_model['timeout'] = 2 load_balancer_pool_health_monitor_prototype_model['type'] = 'http' load_balancer_pool_health_monitor_prototype_model['url_path'] = '/' load_balancer_pool_member_target_prototype_model = {} load_balancer_pool_member_target_prototype_model[ 'address'] = '192.168.3.4' load_balancer_pool_member_prototype_model = {} load_balancer_pool_member_prototype_model['port'] = 80 load_balancer_pool_member_prototype_model[ 'target'] = load_balancer_pool_member_target_prototype_model load_balancer_pool_member_prototype_model['weight'] = 50 load_balancer_pool_session_persistence_prototype_model = {} load_balancer_pool_session_persistence_prototype_model[ 'type'] = 'source_ip' algorithm = 'least_connections' health_monitor = load_balancer_pool_health_monitor_prototype_model protocol = 'http' members = [load_balancer_pool_member_prototype_model] name = 'my-load-balancer-pool' session_persistence = load_balancer_pool_session_persistence_prototype_model response = service.create_load_balancer_pool( load_balancer_id, algorithm, health_monitor, protocol, members=members, name=name, session_persistence=session_persistence, )
Response
The load balancing algorithm.
Possible values: [
least_connections
,round_robin
,weighted_round_robin
]The date and time that this pool was created
The health monitor of this pool.
The seconds to wait between health checks.
Possible values: 2 ≤ value ≤ 60
Example:
5
The health check max retries.
Possible values: 1 ≤ value ≤ 10
Example:
2
The seconds to wait for a response to a health check.
Possible values: 1 ≤ value ≤ 59
Example:
2
The protocol type to use for health checks.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The health check port.
If present, this overrides the pool member port values.
Possible values: 1 ≤ value ≤ 65535
Example:
22
The health check URL path. Applicable when
type
ishttp
orhttps
.Must be in the format of an origin-form request target.
Possible values: Value must match regular expression
^\/(([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})+(\/([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})*)*)?(\?([a-zA-Z0-9-._~!$&'()*+,;=:@\/?]|%[a-fA-F0-9]{2})*)?$
Example:
/
health_monitor
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer-pool
The protocol for this load balancer pool.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this pool
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The PROXY protocol setting for this pool:
v1
: Enabled with version 1 (human-readable header format)v2
: Enabled with version 2 (binary header format)disabled
: Disabled
Supported by load balancers in the
application
family (otherwise alwaysdisabled
).Possible values: [
disabled
,v1
,v2
]The instance group that is managing this pool.
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_group
The backend server members of the pool
The session persistence of this pool.
The session persistence type. The
http_cookie
andapp_cookie
types are applicable only to thehttp
andhttps
protocols.The enumerated values for this property may expand in the future.
Possible values: [
app_cookie
,http_cookie
,source_ip
]The session persistence cookie name. Applicable only for type
app_cookie
. Names starting withIBM
are not allowed.Possible values: Value must match regular expression
^[-A-Za-z0-9!#$%&'*+.^_`~|]+$
Example:
my-cookie-name
session_persistence
Status Code
The pool was created successfully.
An invalid pool prototype object was provided.
A load balancer with the specified identifier could not be found.
A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.
{ "algorithm": "round_robin", "created_at": "2018-12-18T01:07:46.716159Z", "health_monitor": { "delay": 51, "max_retries": 3, "timeout": 21, "type": "http", "url_path": "/" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/528c70d0-acc1-47c7-a32d-698c350f4f81", "id": "528c70d0-acc1-47c7-a32d-698c350f4f81", "members": [], "name": "my-pool", "protocol": "http", "provisioning_status": "create_pending", "proxy_protocol": "disabled", "session_persistence": { "cookie_name": "my-cookie-name", "type": "app_cookie" } }
Delete a load balancer pool
This request deletes a load balancer pool. This operation cannot be reversed. The pool must not currently be the default pool for any listener in the load balancer.
DELETE /load_balancers/{load_balancer_id}/pools/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteLoadBalancerPoolOptions{} options.SetLoadBalancerID(lbID) options.SetID(poolID) response, err := vpcService.DeleteLoadBalancerPool(options)
DeleteLoadBalancerPoolOptions deleteLoadBalancerPoolOptions = new DeleteLoadBalancerPoolOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .build(); Response<Void> response = service.deleteLoadBalancerPool(deleteLoadBalancerPoolOptions).execute();
const response = await vpcService.deleteLoadBalancerPool({ loadBalancerId, id, });
response = service.delete_load_balancer_pool(load_balancer_id, id)
Retrieve a load balancer pool
This request retrieves a single pool specified by the identifier in the URL path.
GET /load_balancers/{load_balancer_id}/pools/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerPoolOptions{} options.SetLoadBalancerID(lbID) options.SetID(poolID) pool, response, err := vpcService.GetLoadBalancerPool(options)
GetLoadBalancerPoolOptions getLoadBalancerPoolOptions = new GetLoadBalancerPoolOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .build(); Response<LoadBalancerPool> response = service.getLoadBalancerPool(getLoadBalancerPoolOptions).execute(); LoadBalancerPool loadBalancerPool = response.getResult();
const response = await vpcService.getLoadBalancerPool({ loadBalancerId, id, });
response = service.get_load_balancer_pool(load_balancer_id, id)
Response
The load balancing algorithm.
Possible values: [
least_connections
,round_robin
,weighted_round_robin
]The date and time that this pool was created
The health monitor of this pool.
The seconds to wait between health checks.
Possible values: 2 ≤ value ≤ 60
Example:
5
The health check max retries.
Possible values: 1 ≤ value ≤ 10
Example:
2
The seconds to wait for a response to a health check.
Possible values: 1 ≤ value ≤ 59
Example:
2
The protocol type to use for health checks.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The health check port.
If present, this overrides the pool member port values.
Possible values: 1 ≤ value ≤ 65535
Example:
22
The health check URL path. Applicable when
type
ishttp
orhttps
.Must be in the format of an origin-form request target.
Possible values: Value must match regular expression
^\/(([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})+(\/([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})*)*)?(\?([a-zA-Z0-9-._~!$&'()*+,;=:@\/?]|%[a-fA-F0-9]{2})*)?$
Example:
/
health_monitor
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer-pool
The protocol for this load balancer pool.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this pool
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The PROXY protocol setting for this pool:
v1
: Enabled with version 1 (human-readable header format)v2
: Enabled with version 2 (binary header format)disabled
: Disabled
Supported by load balancers in the
application
family (otherwise alwaysdisabled
).Possible values: [
disabled
,v1
,v2
]The instance group that is managing this pool.
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_group
The backend server members of the pool
The session persistence of this pool.
The session persistence type. The
http_cookie
andapp_cookie
types are applicable only to thehttp
andhttps
protocols.The enumerated values for this property may expand in the future.
Possible values: [
app_cookie
,http_cookie
,source_ip
]The session persistence cookie name. Applicable only for type
app_cookie
. Names starting withIBM
are not allowed.Possible values: Value must match regular expression
^[-A-Za-z0-9!#$%&'*+.^_`~|]+$
Example:
my-cookie-name
session_persistence
Status Code
The pool was retrieved successfully.
A load balancer with the specified identifier could not be found.
{ "algorithm": "round_robin", "created_at": "2018-12-18T01:07:46.729263Z", "health_monitor": { "delay": 5, "max_retries": 2, "timeout": 2, "type": "http", "url_path": "/" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988", "id": "fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8", "members": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/c8184f3f-3663-41f4-a353-2abb593cd9fe", "id": "c8184f3f-3663-41f4-a353-2abb593cd9fe" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/e0f7d259-e365-41d5-8fe8-fbc8b16341d1", "id": "e0f7d259-e365-41d5-8fe8-fbc8b16341d1" } ], "name": "backend-tcp", "protocol": "tcp", "provisioning_status": "active", "proxy_protocol": "disabled", "session_persistence": { "type": "source_ip" } }
Update a load balancer pool
This request updates a load balancer pool from a pool patch.
PATCH /load_balancers/{load_balancer_id}/pools/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer pool patch
The load balancing algorithm.
Allowable values: [
least_connections
,round_robin
,weighted_round_robin
]The health monitor of this pool.
The seconds to wait between health checks. Must be greater than
timeout
.Possible values: 2 ≤ value ≤ 60
Example:
5
The health check max retries.
Possible values: 1 ≤ value ≤ 10
Example:
2
The seconds to wait for a response to a health check. Must be less than
delay
.Possible values: 1 ≤ value ≤ 59
Example:
2
The protocol type to use for health checks.
Allowable values: [
http
,https
,tcp
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The health check port.
If set, this overrides the pool member port values.
Specify
null
to remove an existing health check port.Possible values: 1 ≤ value ≤ 65535
Example:
22
The health check URL path. Applicable when
type
ishttp
orhttps
.Must be in the format of an origin-form request target.
Possible values: Value must match regular expression
^\/(([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})+(\/([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})*)*)?(\?([a-zA-Z0-9-._~!$&'()*+,;=:@\/?]|%[a-fA-F0-9]{2})*)?$
Example:
/
health_monitor
The name for this load balancer pool. The name must not be used by another pool for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer-pool
The protocol for this load balancer pool.
Load balancers in the
network
family supporttcp
andudp
(ifudp_supported
istrue
). Load balancers in theapplication
family supporttcp
,http
andhttps
.If this pool is associated with a load balancer listener, the specified protocol must match, or be compatible with the listener's protocol. At present, the compatible protocols are
http
andhttps
.Allowable values: [
http
,https
,tcp
,udp
]The PROXY protocol setting for this pool:
v1
: Enabled with version 1 (human-readable header format)v2
: Enabled with version 2 (binary header format)disabled
: Disabled
Supported by load balancers in the
application
family (otherwise alwaysdisabled
).Allowable values: [
disabled
,v1
,v2
]The session persistence of this pool.
The session persistence cookie name. Applicable only for type
app_cookie
. Names starting withIBM
are not allowed.Possible values: Value must match regular expression
^[-A-Za-z0-9!#$%&'*+.^_`~|]+$
Example:
my-cookie-name
The session persistence type. The
http_cookie
andapp_cookie
types are applicable only to thehttp
andhttps
protocols.Allowable values: [
app_cookie
,http_cookie
,source_ip
]
session_persistence
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-pool", "session_persistence": { "type": "source_ip" } }'
options := &vpcv1.UpdateLoadBalancerPoolOptions{} options.SetLoadBalancerID(lbID) options.SetID(poolID) options.SetProtocol("tcp") pool, response, err := vpcService.UpdateLoadBalancerPool(options)
UpdateLoadBalancerPoolOptions updateLoadBalancerPoolOptions = new UpdateLoadBalancerPoolOptions.Builder() .loadBalancerId(loadBalancerId) .id(id) .name(name) .build(); Response<LoadBalancerPool> response = service.updateLoadBalancerPool(updateLoadBalancerPoolOptions).execute(); LoadBalancerPool loadBalancerPool = response.getResult();
const params = { loadBalancerId, id, algorithm, name: 'my-load-balancer-pool', }; const response = await vpcService.updateLoadBalancerPool(params);
load_balancer_pool_health_monitor_patch_model = {} load_balancer_pool_health_monitor_patch_model['delay'] = 5 load_balancer_pool_health_monitor_patch_model['max_retries'] = 2 load_balancer_pool_health_monitor_patch_model['port'] = 22 load_balancer_pool_health_monitor_patch_model['timeout'] = 2 load_balancer_pool_health_monitor_patch_model['type'] = 'http' load_balancer_pool_health_monitor_patch_model['url_path'] = '/' load_balancer_pool_session_persistence_patch_model = {} load_balancer_pool_session_persistence_patch_model['type'] = 'source_ip' algorithm = 'least_connections' health_monitor = load_balancer_pool_health_monitor_patch_model name = 'my-load-balancer-pool' protocol = 'http' session_persistence = load_balancer_pool_session_persistence_patch_model response = service.update_load_balancer_pool( load_balancer_id, id, algorithm=algorithm, health_monitor=health_monitor, name=name, protocol=protocol, session_persistence=session_persistence, )
Response
The load balancing algorithm.
Possible values: [
least_connections
,round_robin
,weighted_round_robin
]The date and time that this pool was created
The health monitor of this pool.
The seconds to wait between health checks.
Possible values: 2 ≤ value ≤ 60
Example:
5
The health check max retries.
Possible values: 1 ≤ value ≤ 10
Example:
2
The seconds to wait for a response to a health check.
Possible values: 1 ≤ value ≤ 59
Example:
2
The protocol type to use for health checks.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The health check port.
If present, this overrides the pool member port values.
Possible values: 1 ≤ value ≤ 65535
Example:
22
The health check URL path. Applicable when
type
ishttp
orhttps
.Must be in the format of an origin-form request target.
Possible values: Value must match regular expression
^\/(([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})+(\/([a-zA-Z0-9-._~!$&'()*+,;=:@]|%[a-fA-F0-9]{2})*)*)?(\?([a-zA-Z0-9-._~!$&'()*+,;=:@\/?]|%[a-fA-F0-9]{2})*)?$
Example:
/
health_monitor
The pool's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The name for this load balancer pool. The name is unique across all pools for the load balancer.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-load-balancer-pool
The protocol for this load balancer pool.
The enumerated values for this property may expand in the future.
Possible values: [
http
,https
,tcp
,udp
]The provisioning status of this pool
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The PROXY protocol setting for this pool:
v1
: Enabled with version 1 (human-readable header format)v2
: Enabled with version 2 (binary header format)disabled
: Disabled
Supported by load balancers in the
application
family (otherwise alwaysdisabled
).Possible values: [
disabled
,v1
,v2
]The instance group that is managing this pool.
The CRN for this instance group
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance-group:1e09281b-f177-46fb-baf1-bc152b2e391a
The URL for this instance group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instance_groups/1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this instance group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this instance group. The name is unique across all instance groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-group
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
instance_group
The backend server members of the pool
The session persistence of this pool.
The session persistence type. The
http_cookie
andapp_cookie
types are applicable only to thehttp
andhttps
protocols.The enumerated values for this property may expand in the future.
Possible values: [
app_cookie
,http_cookie
,source_ip
]The session persistence cookie name. Applicable only for type
app_cookie
. Names starting withIBM
are not allowed.Possible values: Value must match regular expression
^[-A-Za-z0-9!#$%&'*+.^_`~|]+$
Example:
my-cookie-name
session_persistence
Status Code
The pool update request was accepted.
An invalid pool patch was provided.
A pool with the specified identifier could not be found.
{ "algorithm": "round_robin", "created_at": "2018-12-18T01:07:46.729263Z", "health_monitor": { "delay": 5, "max_retries": 2, "timeout": 2, "type": "http", "url_path": "/" }, "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988", "id": "fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8", "members": [ { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/c8184f3f-3663-41f4-a353-2abb593cd9fe", "id": "c8184f3f-3663-41f4-a353-2abb593cd9fe" }, { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/fa248e5d-86b6-4c3d-a0c3-3df1bf59d5b8/members/e0f7d259-e365-41d5-8fe8-fbc8b16341d1", "id": "e0f7d259-e365-41d5-8fe8-fbc8b16341d1" } ], "name": "my-pool", "protocol": "tcp", "provisioning_status": "update_pending", "proxy_protocol": "disabled", "session_persistence": { "type": "source_ip" } }
List all members of a load balancer pool
This request lists all members of a load balancer pool.
GET /load_balancers/{load_balancer_id}/pools/{pool_id}/members
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListLoadBalancerPoolMembersOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) members, response, err := vpcService.ListLoadBalancerPoolMembers(options)
ListLoadBalancerPoolMembersOptions listLoadBalancerPoolMembersOptions = new ListLoadBalancerPoolMembersOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .build(); Response<LoadBalancerPoolMemberCollection> response = service.listLoadBalancerPoolMembers(listLoadBalancerPoolMembersOptions).execute(); LoadBalancerPoolMemberCollection loadBalancerPoolMemberCollection = response.getResult();
const response = await vpcService.listLoadBalancerPoolMembers({ loadBalancerId, id: poolId, });
response = service.list_load_balancer_pool_members( load_balancer_id, pool_id)
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of members
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
next
Status Code
The members of the load balancer pool were retrieved successfully.
A load balancer or pool with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members?limit=50" }, "limit": 50, "members": [ { "created_at": "2018-12-18T01:07:46.733487Z", "health": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members/54aec7cf-0261-11e9-8317-bec54e704988", "id": "54aec7cf-0261-11e9-8317-bec54e704988", "port": 80, "provisioning_status": "active", "target": { "address": "10.0.0.25" }, "weight": 50 }, { "created_at": "2018-12-18T01:07:46.734764Z", "health": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members/daebeb48-1658-4772-8ca9-e410cd6e1415", "id": "daebeb48-1658-4772-8ca9-e410cd6e1415", "port": 80, "provisioning_status": "active", "target": { "address": "10.0.0.29" }, "weight": 50 } ], "total_count": 2 }
Create a member in a load balancer pool
This request creates a new member and adds the member to the pool.
POST /load_balancers/{load_balancer_id}/pools/{pool_id}/members
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The prototype object for a new load balancer pool member. For load balancers in the
network
family, the same port
and target
tuple cannot be shared by a pool member
of any other load balancer.
The port the member will receive load balancer traffic on. Applies only to load balancer traffic received on a listener with a single port. (If the traffic is received on a listener with a port range, the member will receive the traffic on the same port the listener received it on.)
This port will also be used for health checks unless the
port
property ofhealth_monitor
property is specified.The port must be unique across all members for all pools associated with this pool's listener.
Possible values: 1 ≤ value ≤ 65535
Example:
80
The pool member target. Load balancers in the
network
family support virtual server instances. Load balancers in theapplication
family support IP addresses. If the load balancer has route mode enabled, the member must be in a zone the load balancer has a subnet in.target
Weight of the server member. Applicable only if the pool algorithm is
weighted_round_robin
.Possible values: 0 ≤ value ≤ 100
Default:
50
Example:
50
curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "port": 80, "target": { "address": "10.0.0.99" } }'
options := &vpcv1.CreateLoadBalancerPoolMemberOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) options.SetPort(1234) options.SetTarget(&vpcv1.LoadBalancerPoolMemberTargetPrototype{ Address: &ip, }) member, response, err := vpcService.CreateLoadBalancerPoolMember(options)
LoadBalancerPoolMemberTargetPrototypeIP loadBalancerPoolMemberTargetPrototypeModel = new LoadBalancerPoolMemberTargetPrototypeIP.Builder() .address(address) .build(); CreateLoadBalancerPoolMemberOptions createLoadBalancerPoolMemberOptions = new CreateLoadBalancerPoolMemberOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .port(Long.valueOf("80")) .target(loadBalancerPoolMemberTargetPrototypeModel) .build(); Response<LoadBalancerPoolMember> response = service.createLoadBalancerPoolMember(createLoadBalancerPoolMemberOptions).execute(); LoadBalancerPoolMember loadBalancerPoolMember = response.getResult();
const loadBalancerPoolMemberTargetPrototypeModel = { id: { address: '192.168.3.4', }, }; const params = { loadBalancerId, poolId, port: 80, target: loadBalancerPoolMemberTargetPrototypeModel, weight: 50, }; const response = await vpcService.createLoadBalancerPoolMember(params);
load_balancer_pool_member_target_prototype_model = {} load_balancer_pool_member_target_prototype_model[ 'address'] = '192.168.3.4' port = 80 target = load_balancer_pool_member_target_prototype_model weight = 50 response = service.create_load_balancer_pool_member( load_balancer_id, pool_id, port, target, weight=weight, )
Response
The date and time that this member was created
Health of the server member in the pool.
Possible values: [
faulted
,ok
,unknown
]The member's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004/members/80294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool member
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The port the member will receive load balancer traffic on. Applies only to load balancer traffic received on a listener with a single port. (If the traffic is received on a listener with a port range, the member will receive the traffic on the same port the listener received it on.)
This port will also be used for health checks unless the
port
property ofhealth_monitor
property is specified.Possible values: 1 ≤ value ≤ 65535
Example:
80
The provisioning status of this member
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The pool member target. Load balancers in the
network
family support virtual server instances. Load balancers in theapplication
family support IP addresses. If the load balancer has route mode enabled, the member must be in a zone the load balancer has a subnet in.The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Weight of the server member. Applicable only if the pool algorithm is
weighted_round_robin
.Possible values: 0 ≤ value ≤ 100
Example:
50
Status Code
The member was created successfully.
An invalid member prototype object was provided.
A load balancer or pool with the specified identifier could not be found.
The load balancer pool member prototype object conflicts with another load balancer pool member in the VPC.
{ "created_at": "2018-12-18T07:51:40.298050558Z", "health": "unknown", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members/c1034809-0299-11e9-a178-22dd3503b06c", "id": "c1034809-0299-11e9-a178-22dd3503b06c", "port": 80, "provisioning_status": "create_pending", "target": { "address": "10.0.0.99" }, "weight": 50 }
Replace load balancer pool members
This request replaces the existing members of the load balancer pool with new members created from the collection of member prototype objects.
PUT /load_balancers/{load_balancer_id}/pools/{pool_id}/members
Request
Path Parameters
The load balancer identifier
The pool identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The collection of prototype objects for load balancer pool members. For load balancers
in the network
family, the same port
and target
tuple cannot be shared by a pool
member of any other load balancer.
The member prototype objects for this pool.
curl -X PUT "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '[ { "port": 80, "target": { "address": "10.0.0.99" } }, { "port": 81, "target": { "address": "10.0.0.100" } } ]'
options := &vpcv1.ReplaceLoadBalancerPoolMembersOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) options.SetMembers([]vpcv1.LoadBalancerPoolMemberPrototype{ vpcv1.LoadBalancerPoolMemberPrototype{ Port: core.Int64Ptr(2345), Target: &vpcv1.LoadBalancerPoolMemberTargetPrototype{ Address: &ip, }, }, }) member, response, err := vpcService.ReplaceLoadBalancerPoolMembers(options)
LoadBalancerPoolMemberTargetPrototypeIP loadBalancerPoolMemberTargetPrototypeModel = new LoadBalancerPoolMemberTargetPrototypeIP.Builder() .address("192.168.3.4") .build(); LoadBalancerPoolMemberPrototype loadBalancerPoolMemberPrototypeModel = new LoadBalancerPoolMemberPrototype.Builder() .port(Long.valueOf("80")) .target(loadBalancerPoolMemberTargetPrototypeModel) .weight(Long.valueOf("50")) .build(); ReplaceLoadBalancerPoolMembersOptions replaceLoadBalancerPoolMembersOptions = new ReplaceLoadBalancerPoolMembersOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .members(new java.util.ArrayList<LoadBalancerPoolMemberPrototype>(java.util.Arrays.asList(loadBalancerPoolMemberPrototypeModel))) .build(); Response<LoadBalancerPoolMemberCollection> response = service.replaceLoadBalancerPoolMembers(replaceLoadBalancerPoolMembersOptions).execute();
const loadBalancerPoolMemberPrototypeModel = { port: 80, weight: 50, }; const params = { loadBalancerId, id: poolId, members: [loadBalancerPoolMemberPrototypeModel], }; const response = await vpcService.replaceLoadBalancerPoolMembers(params);
load_balancer_pool_member_target_prototype_model = {} load_balancer_pool_member_target_prototype_model[ 'address'] = '192.168.3.4' load_balancer_pool_member_prototype_model = {} load_balancer_pool_member_prototype_model['port'] = 82 load_balancer_pool_member_prototype_model[ 'target'] = load_balancer_pool_member_target_prototype_model load_balancer_pool_member_prototype_model['weight'] = 50 members = [load_balancer_pool_member_prototype_model] response = service.replace_load_balancer_pool_members( load_balancer_id, pool_id, members, )
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of members
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
next
Status Code
The update request was accepted.
An invalid member prototype object was provided.
A load balancer or pool with the specified identifier could not be found.
A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members?limit=50" }, "limit": 50, "members": [ { "created_at": "2019-04-08T20:58:24.433922161Z", "health": "unknown", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/1bff8de8-e26a-4b88-a542-53f0bf9a0419/pools/3c4b9885-08cb-44f7-b947-49c1e9f19ea7/members/8fabf93b-0ab7-42dd-b441-f52064621536", "id": "8fabf93b-0ab7-42dd-b441-f52064621536", "port": 80, "provisioning_status": "create_pending", "target": { "address": "10.0.0.99" }, "weight": 50 }, { "created_at": "2019-04-08T20:58:24.433922161Z", "health": "unknown", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/1bff8de8-e26a-4b88-a542-53f0bf9a0419/pools/3c4b9885-08cb-44f7-b947-49c1e9f19ea7/members/58914405-9f3b-419e-9dd9-48a4eb3d255d", "id": "58914405-9f3b-419e-9dd9-48a4eb3d255d", "port": 81, "provisioning_status": "create_pending", "target": { "address": "10.0.0.100" }, "weight": 50 } ], "total_count": 2 }
Delete a load balancer pool member
This request deletes a member from the pool. This operation cannot be reversed.
DELETE /load_balancers/{load_balancer_id}/pools/{pool_id}/members/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
The member identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members/$member_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteLoadBalancerPoolMemberOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) options.SetID(memberID) response, err := vpcService.DeleteLoadBalancerPoolMember(options)
DeleteLoadBalancerPoolMemberOptions deleteLoadBalancerPoolMemberOptions = new DeleteLoadBalancerPoolMemberOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .id(id) .build(); Response<Void> response = service.deleteLoadBalancerPoolMember(deleteLoadBalancerPoolMemberOptions).execute();
const response = await vpcService.deleteLoadBalancerPoolMember({ loadBalancerId, poolId, id, });
response = service.delete_load_balancer_pool_member( load_balancer_id, pool_id, id)
Retrieve a load balancer pool member
This request retrieves a single member specified by the identifier in the URL path.
GET /load_balancers/{load_balancer_id}/pools/{pool_id}/members/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
The member identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members/$member_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetLoadBalancerPoolMemberOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) options.SetID(memberID) member, response, err := vpcService.GetLoadBalancerPoolMember(options)
GetLoadBalancerPoolMemberOptions getLoadBalancerPoolMemberOptions = new GetLoadBalancerPoolMemberOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .id(id) .build(); Response<LoadBalancerPoolMember> response = service.getLoadBalancerPoolMember(getLoadBalancerPoolMemberOptions).execute(); LoadBalancerPoolMember loadBalancerPoolMember = response.getResult();
const response = await vpcService.getLoadBalancerPoolMember({ loadBalancerId, poolId, id, });
response = service.get_load_balancer_pool_member( load_balancer_id, pool_id, id)
Response
The date and time that this member was created
Health of the server member in the pool.
Possible values: [
faulted
,ok
,unknown
]The member's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004/members/80294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool member
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The port the member will receive load balancer traffic on. Applies only to load balancer traffic received on a listener with a single port. (If the traffic is received on a listener with a port range, the member will receive the traffic on the same port the listener received it on.)
This port will also be used for health checks unless the
port
property ofhealth_monitor
property is specified.Possible values: 1 ≤ value ≤ 65535
Example:
80
The provisioning status of this member
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The pool member target. Load balancers in the
network
family support virtual server instances. Load balancers in theapplication
family support IP addresses. If the load balancer has route mode enabled, the member must be in a zone the load balancer has a subnet in.The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Weight of the server member. Applicable only if the pool algorithm is
weighted_round_robin
.Possible values: 0 ≤ value ≤ 100
Example:
50
Status Code
The member was retrieved successfully.
A member with the specified identifier could not be found.
{ "created_at": "2018-12-18T01:07:46.733487Z", "health": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members/54aec7cf-0261-11e9-8317-bec54e704988", "id": "54aec7cf-0261-11e9-8317-bec54e704988", "port": 80, "provisioning_status": "active", "target": { "address": "10.0.0.25" }, "weight": 50 }
Update a load balancer pool member
This request updates an existing member from a member patch.
PATCH /load_balancers/{load_balancer_id}/pools/{pool_id}/members/{id}
Request
Path Parameters
The load balancer identifier
The pool identifier
The member identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The load balancer pool member patch
The port the member will receive load balancer traffic on. Applies only to load balancer traffic received on a listener with a single port. (If the traffic is received on a listener with a port range, the member will receive the traffic on the same port the listener received it on.)
This port will also be used for health checks unless the
port
property ofhealth_monitor
property is specified.The port must be unique across all members for all pools associated with this pool's listener.
Possible values: 1 ≤ value ≤ 65535
Example:
80
The pool member target. Load balancers in the
network
family support virtual server instances. Load balancers in theapplication
family support IP addresses. If the load balancer has route mode enabled, the member must be in a zone the load balancer has a subnet in.target
Weight of the server member. Applicable only if the pool algorithm is
weighted_round_robin
.Possible values: 0 ≤ value ≤ 100
Example:
50
curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members/$member_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{"port": 82}'
options := &vpcv1.UpdateLoadBalancerPoolMemberOptions{} options.SetLoadBalancerID(lbID) options.SetPoolID(poolID) options.SetID(memberID) options.SetPort(3434) member, response, err := vpcService.UpdateLoadBalancerPoolMember(options)
UpdateLoadBalancerPoolMemberOptions updateLoadBalancerPoolMemberOptions = new UpdateLoadBalancerPoolMemberOptions.Builder() .loadBalancerId(loadBalancerId) .poolId(poolId) .id(id) .name(name) .build(); Response<LoadBalancerPoolMember> response = service.updateLoadBalancerPoolMember(updateLoadBalancerPoolMemberOptions).execute(); LoadBalancerPoolMember loadBalancerPoolMember = response.getResult();
const loadBalancerPoolMemberPrototypeModel = { port: 80, weight: 50, }; const response = await vpcService.updateLoadBalancerPoolMember({ loadBalancerId, poolId, id, });
load_balancer_pool_member_target_prototype_model = {} load_balancer_pool_member_target_prototype_model[ 'address'] = '192.168.3.4' port = 81 target = load_balancer_pool_member_target_prototype_model weight = 52 response = service.update_load_balancer_pool_member( load_balancer_id, pool_id, id, port=port, target=target, weight=weight, )
Response
The date and time that this member was created
Health of the server member in the pool.
Possible values: [
faulted
,ok
,unknown
]The member's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727/pools/70294e14-4e61-11e8-bcf4-0242ac110004/members/80294e14-4e61-11e8-bcf4-0242ac110004
The unique identifier for this load balancer pool member
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
70294e14-4e61-11e8-bcf4-0242ac110004
The port the member will receive load balancer traffic on. Applies only to load balancer traffic received on a listener with a single port. (If the traffic is received on a listener with a port range, the member will receive the traffic on the same port the listener received it on.)
This port will also be used for health checks unless the
port
property ofhealth_monitor
property is specified.Possible values: 1 ≤ value ≤ 65535
Example:
80
The provisioning status of this member
The enumerated values for this property may expand in the future.
Possible values: [
active
,create_pending
,delete_pending
,failed
,update_pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The pool member target. Load balancers in the
network
family support virtual server instances. Load balancers in theapplication
family support IP addresses. If the load balancer has route mode enabled, the member must be in a zone the load balancer has a subnet in.The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The URL for this virtual server instance
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^https:\/\/([^\/?#]*)([^?#]*)/instances/[-0-9a-z_]+$
Example:
https://us-south.iaas.cloud.ibm.com/v1/instances/0717_1e09281b-f177-46fb-b1f1-bc152b2e391a
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_1e09281b-f177-46f2-b1f1-bc152b2e391a
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
target
Weight of the server member. Applicable only if the pool algorithm is
weighted_round_robin
.Possible values: 0 ≤ value ≤ 100
Example:
50
Status Code
The member update request was accepted.
An invalid pool member patch was provided.
A pool member with the specified identifier could not be found.
The load balancer pool member patch conflicts with another load balancer pool member in the VPC.
{ "created_at": "2018-12-18T07:51:40.29805Z", "health": "unknown", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/2c791a20-4109-4484-894a-09f332753169/pools/54ad563a-0261-11e9-8317-bec54e704988/members/c1034809-0299-11e9-a178-22dd3503b06c", "id": "c1034809-0299-11e9-a178-22dd3503b06c", "port": 82, "provisioning_status": "update_pending", "target": { "address": "10.0.0.99" }, "weight": 99 }
List all endpoint gateways
This request lists all endpoint gateways in the region. An endpoint gateway maps one or more reserved IPs in a VPC to a target outside the VPC.
GET /endpoint_gateways
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]Filters the collection to resources with a
name
property matching the exact specified name.A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
lifecycle_state
property matching one of the specified comma-separated values.Allowable values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Possible values: number of items ≥ 1, contains only unique items
Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
Filters the collection to endpoint gateways with an
allow_dns_resolution_binding
property matching the specified value.
curl -X GET "$vpc_api_endpoint/v1/endpoint_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListEndpointGatewaysOptions() endpointGateways, response, err := vpcService.ListEndpointGateways(options)
ListEndpointGatewaysOptions listEndpointGatewaysOptions = new ListEndpointGatewaysOptions.Builder() .build(); Response<EndpointGatewayCollection> response = service.listEndpointGateways(listEndpointGatewaysOptions).execute(); EndpointGatewayCollection endpointGatewayCollection = response.getResult();
const response = await vpcService.listEndpointGateways();
response = service.list_endpoint_gateways() endpoint_gateways = response.get_result()['endpoint_gateways']
Response
Collection of endpoint gateways
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways?start=ffd653466e284937896724b2dd044c9c&limit=20
next
Status Code
The endpoint gateways were retrieved successfully.
{ "endpoint_gateways": [ { "allow_dns_resolution_binding": true, "created_at": "2020-07-24T19:42:46Z", "crn": "crn:[...]", "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "ips": [ { "address": "10.240.0.7", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0716-bb7e061d-7259-45b6-a0da-416ace665269", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-endpoint-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "endpoint_gateway", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "service_endpoints": [ "time.adn.networklayer.com" ], "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "name": "my-private-path-service", "resource_type": "private_path_service_gateway" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "name": "my-vpc", "resource_type": "vpc" } }, { "allow_dns_resolution_binding": false, "created_at": "2020-07-24T19:43:56Z", "crn": "crn:[...]", "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-badc3b88-b9c2-46c3-acb1-2fd4361f6f7d", "id": "r134-badc3b88-b9c2-46c3-acb1-2fd4361f6f7d", "ips": [ { "address": "10.240.64.4", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-236a7fcf-3f9b-4612-8827-e7eddd216b6b", "id": "0716-236a7fcf-3f9b-4612-8827-e7eddd216b6b", "lifecycle_state": "stable", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-endpoint-gateway-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "endpoint_gateway", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "service_endpoints": [ "time.adn.networklayer.com" ], "target": { "name": "ibm-ntp-server", "resource_type": "provider_infrastructure_service" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "r134-e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-other-vpc", "resource_type": "vpc" } } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways?limit=50" }, "limit": 50, "total_count": 2 }
Create an endpoint gateway
This request creates a new endpoint gateway. An endpoint gateway maps one or more reserved IPs in a VPC to a target outside the VPC.
POST /endpoint_gateways
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.endpoint-gateway.endpoint-gateway.create
is.endpoint-gateway.endpoint-gateway.attach
Generated for each resource being attached to the endpoint gateway (such as a security group).
is.subnet.reserved-ip.create
Generated for each reserved IP created that was specified in
ips
is.subnet.reserved-ip.attach
Generated for each reserved IP that was specified in
ips
.is.security-group.security-group.attach
Generated for each security group that was specified in
security_groups
.is.private-path-service-gateway.endpoint-gateway-binding.create
Generated when the target is a private path service gateway
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The endpoint gateway prototype
The target to use for this endpoint gateway. Must not already be the target of another endpoint gateway in the VPC.
The VPC this endpoint gateway will reside in
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
vpc
Indicates whether to allow DNS resolution for this endpoint gateway when the VPC this endpoint gateway resides in has a DNS resolution binding to a VPC with
dns.enable_hub
set totrue
.Must be
true
if the VPC this endpoint gateway resides in hasdns.enable_hub
set totrue
.Default:
true
The reserved IPs to bind to this endpoint gateway. At most one reserved IP per zone is allowed.
ips
The name for this endpoint gateway. The name must not be used by another endpoint gateway in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-endpoint-gateway
The resource group to use. If unspecified, the account's default resource group will be used.
The security groups to use for this endpoint gateway. If unspecified, the VPC's default security group is used.
Possible values: contains only unique items
Examples:Viewsecurity_groups
curl -X POST "$vpc_api_endpoint/v1/endpoint_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-endpoint-gateway-1", "target": { "name": "ibm-ntp-server", "resource_type":"provider_infrastructure_service" }, "vpc": { "id": "f025b503-ae66-46de-a011-3bd08fd5f7bf"}, "ips":[ {"id":"914995db-190b-4373-b4bc-22561da6cbda"} ] }'
options := &vpcv1.CreateEndpointGatewayOptions{} options.SetName(name) options.SetVPC(&vpcv1.VPCIdentity{ ID: &vpcID, }) targetName := "ibm-ntp-server" providerInfrastructureService := "provider_infrastructure_service" options.SetTarget( &vpcv1.EndpointGatewayTargetPrototype { ResourceType: &providerInfrastructureService, Name: &targetName, }, ) endpointGateway, response, err := vpcService.CreateEndpointGateway(options)
EndpointGatewayTargetPrototypeProviderCloudServiceIdentityProviderCloudServiceIdentityByCRN endpointGatewayTargetPrototypeModel = new EndpointGatewayTargetPrototypeProviderCloudServiceIdentityProviderCloudServiceIdentityByCRN.Builder() .crn(crn) .build(); VPCIdentityById vpcIdentityModel = new VPCIdentityById.Builder() .id(vpcId) .build(); CreateEndpointGatewayOptions createEndpointGatewayOptions = new CreateEndpointGatewayOptions.Builder() .target(endpointGatewayTargetPrototypeModel) .vpc(vpcIdentityModel) .name("my-endpoint-gateway") .build(); Response<EndpointGateway> response = service.createEndpointGateway(createEndpointGatewayOptions).execute(); EndpointGateway endpointGateway = response.getResult();
const params = { target: { name: 'ibm-ntp-server', resource_type: 'provider_infrastructure_service', }, vpc: { id: vpcID }, name: 'my-endpoint-gateway', }; const response = await vpcService.createEndpointGateway(params);
target_prototype_model = {} target_prototype_model['resource_type'] = 'provider_infrastructure_service' target_prototype_model['name'] = 'ibm-ntp-server' vpc_identity_model = {} vpc_identity_model['id'] = vpc_id name = 'my-endpoint-gateway' response = service.create_endpoint_gateway( target_prototype_model, vpc_identity_model, name=name)
Response
Indicates whether to allow DNS resolution for this endpoint gateway when the VPC this endpoint gateway resides in has a DNS resolution binding to a VPC with
dns.enable_hub
set totrue
.The date and time that the endpoint gateway was created.
The CRN for this endpoint gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this endpoint gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this endpoint gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reserved IPs bound to this endpoint gateway.
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the endpoint gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this endpoint gateway. The name is unique across all endpoint gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-endpoint-gateway
The resource group for this endpoint gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
endpoint_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this endpoint gateway.
Possible values: number of items ≥ 0, contains only unique items
The fully qualified domain names for the target service.
The target for this endpoint gateway.
The VPC this endpoint gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The fully qualified domain name for the target service
Example:
my-cloudant-instance.appdomain.cloud
Status Code
The endpoint gateway was created successfully.
An invalid endpoint gateway prototype object was provided.
The endpoint gateway prototype object specifies a reserved IP that is already in use, or a reserved IP prototype object specifies a subnet with no available IP addresses.
{ "allow_dns_resolution_binding": true, "created_at": "2020-07-24T19:42:46Z", "crn": "crn:[...]", "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "ips": [ { "address": "10.240.0.7", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0716-bb7e061d-7259-45b6-a0da-416ace665269", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-endpoint-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "endpoint_gateway", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "service_endpoints": [ "time.adn.networklayer.com" ], "target": { "name": "ibm-ntp-server", "resource_type": "provider_infrastructure_service" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "name": "my-vpc", "resource_type": "vpc" } }
List all reserved IPs bound to an endpoint gateway
This request lists all reserved IPs bound to an endpoint gateway.
GET /endpoint_gateways/{endpoint_gateway_id}/ips
Request
Path Parameters
The endpoint gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
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 thecreated_at
property in descending order, and the valuename
sorts it by thename
property in ascending order.Allowable values: [
address
,created_at
,name
]Default:
address
Example:
name
curl -X GET "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id/ips?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListEndpointGatewayIpsOptions(endpoint_gateway_id) reservedIPs, response, err := vpcService.ListEndpointGatewayIps(options)
ListEndpointGatewayIpsOptions listEndpointGatewayIpsOptions = new ListEndpointGatewayIpsOptions.Builder() .endpointGatewayId(endpointGatewayId) .limit(Long.valueOf("1")) .build(); Response<ReservedIPCollectionEndpointGatewayContext> response = service.listEndpointGatewayIps(listEndpointGatewayIpsOptions).execute(); ReservedIPCollectionEndpointGatewayContext reservedIpCollectionEndpointGatewayContextResult = response.getResult();
const response = await vpcService.listEndpointGatewayIps({ endpointGatewayId, });
response = service.list_endpoint_gateway_ips(endpoint_gateway_id) ips = response.get_result()['ips']
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/d7cc5196-9864-48c4-82d8-3f30da41fcc5/ips?limit=20
first
Collection of reserved IPs bound to an endpoint gateway
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/d7cc5196-9864-48c4-82d8-3f30da41fcc5/ips?start=90ac13871b604023ab8b827178518328&limit=20
next
Status Code
The bound reserved IPs were retrieved successfully.
An endpoint gateway with the specified identifier could not be found.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4/ips?limit=50" }, "ips": [ { "address": "10.240.0.7", "auto_delete": true, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "id": "r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" } }, { "address": "10.240.64.4", "auto_delete": true, "created_at": "2020-07-24T19:53:23Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0726-ebe8b8e7-d20c-4175-92bf-835704ed331b/ips/0726-16f16cdc-6488-4ef3-8c47-969212e844c1", "id": "0726-16f16cdc-6488-4ef3-8c47-969212e844c1", "lifecycle_state": "stable", "name": "my-reserved-ip-2", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "id": "r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" } } ], "limit": 50, "total_count": 2 }
Unbind a reserved IP from an endpoint gateway
This request unbinds the specified reserved IP from the specified endpoint gateway. If
the reserved IP has auto_delete
set to true
, the reserved IP will be deleted.
DELETE /endpoint_gateways/{endpoint_gateway_id}/ips/{id}
Request
Path Parameters
The endpoint gateway identifier
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := NewRemoveEndpointGatewayIPOptions(endpoint_gateway_id, id) response, err := vpcService.RemoveEndpointGatewayIP(options)
RemoveEndpointGatewayIpOptions removeEndpointGatewayIpOptions = new RemoveEndpointGatewayIpOptions.Builder() .endpointGatewayId(endpointGatewayId) .id(id) .build(); Response<Void> response = service.removeEndpointGatewayIp(removeEndpointGatewayIpOptions).execute();
const response = await vpcService.removeEndpointGatewayIp({ endpointGatewayId, id, });
response = service.remove_endpoint_gateway_ip(endpoint_gateway_id, reserved_ip_id)
Retrieve a reserved IP bound to an endpoint gateway
This request retrieves the specified reserved IP address if it is bound to the endpoint gateway specified in the URL.
GET /endpoint_gateways/{endpoint_gateway_id}/ips/{id}
Request
Path Parameters
The endpoint gateway identifier
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetEndpointGatewayIPOptions(endpoint_gateway_id, id) reservedIP, response, err := vpcService.GetEndpointGatewayIP(options)
GetEndpointGatewayIpOptions getEndpointGatewayIpOptions = new GetEndpointGatewayIpOptions.Builder() .endpointGatewayId(endpointGatewayId) .id(id) .build(); Response<ReservedIP> response = service.getEndpointGatewayIp(getEndpointGatewayIpOptions).execute(); ReservedIP reservedIp = response.getResult();
const response = await vpcService.getEndpointGatewayIp({ endpointGatewayId, id, });
response = service.get_endpoint_gateway_ip(endpoint_gateway_id, reserved_ip_id) if response.status_code == 200: reserved_ip = response.get_result()
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The bound reserved IP was retrieved successfully.
The bound reserved IP with the specified identifier could not be found
{ "address": "10.240.0.7", "auto_delete": true, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "id": "r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" } }
Bind a reserved IP to an endpoint gateway
This request binds the specified reserved IP to the specified endpoint gateway. The reserved IP:
- must currently be unbound, or not required by its target
- must not be in the same zone as any other reserved IP bound to the endpoint gateway
PUT /endpoint_gateways/{endpoint_gateway_id}/ips/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.endpoint-gateway.endpoint-gateway.attach
Generated when a reserved IP is attached to this endpoint gateway
is.subnet.reserved-ip.attach
Generated when a reserved IP is attached to this endpoint gateway
Request
Path Parameters
The endpoint gateway identifier
The reserved IP identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X PUT "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id/ips/$id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewAddEndpointGatewayIPOptions(endpoint_gateway_id, id) reservedIP, response, err := vpcService.AddEndpointGatewayIP(options)
AddEndpointGatewayIpOptions addEndpointGatewayIpOptions = new AddEndpointGatewayIpOptions.Builder() .endpointGatewayId(endpointGatewayId) .id(id) .build(); Response<ReservedIP> response = service.addEndpointGatewayIp(addEndpointGatewayIpOptions).execute();
const response = await vpcService.addEndpointGatewayIp({ endpointGatewayId, id, });
response = service.add_endpoint_gateway_ip(endpoint_gateway_id, reserved_ip_id)
Response
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.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
Indicates whether this reserved IP member will be automatically deleted when either
target
is deleted, or the reserved IP is unbound.The date and time that the reserved IP was created
The URL for this reserved IP
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/subnets/0717-bea6a632-5e13-42a4-b4b8-31dc877abfe4/reserved_ips/0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The lifecycle state of the reserved IP
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The owner of the reserved IP
Possible values: [
provider
,user
]Example:
user
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The target this reserved IP is bound to.
If absent, this reserved IP is provider-owned or unbound.
Status Code
The reserved IP was successfully bound to the endpoint gateway.
The specified reserved IP could not be bound to the endpoint gateway.
An endpoint gateway with the specified identifier could not be found.
{ "address": "10.240.0.7", "auto_delete": true, "created_at": "2020-07-24T19:52:18Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "id": "0716-9faf2f32-8528-4180-a14d-c1f6c5c83292", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "owner": "user", "resource_type": "subnet_reserved_ip", "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "id": "r134-fb050c0c-b33a-44b1-9eae-4ae6e6ebaba4", "name": "my-endpoint-gateway-1", "resource_type": "endpoint_gateway" } }
Delete an endpoint gateway
This request deletes an endpoint gateway. This operation cannot be reversed.
Reserved IPs that were bound to the endpoint gateway will be released if their
auto_delete
property is set to true.
DELETE /endpoint_gateways/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.endpoint-gateway.endpoint-gateway.delete
is.subnet.reserved-ip.detach
Generated for each reserved IP in
ips
.is.endpoint-gateway.endpoint-gateway.detach
Generated for each resource being detached from the endpoint gateway (such as a security group)
is.subnet.reserved-ip.delete
Generated for each reserved IP in
ips
for whichauto_delete
istrue
is.security-group.security-group.detach
Generated for each security group in
security_groups
.is.private-path-service-gateway.endpoint-gateway-binding.delete
Generated when the target is a private path service gateway
Request
Path Parameters
The endpoint gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeleteEndpointGatewayOptions(id) response, err := vpcService.DeleteEndpointGateway(options)
DeleteEndpointGatewayOptions deleteEndpointGatewayOptions = new DeleteEndpointGatewayOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteEndpointGateway(deleteEndpointGatewayOptions).execute();
const response = await vpcService.deleteEndpointGateway({ id });
response = service.delete_endpoint_gateway(id)
Retrieve an endpoint gateway
This request retrieves a single endpoint gateway specified by the identifier in the URL.
GET /endpoint_gateways/{id}
Request
Path Parameters
The endpoint gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetEndpointGatewayOptions(id) endpointGateway, response, err := vpcService.GetEndpointGateway(options)
GetEndpointGatewayOptions getEndpointGatewayOptions = new GetEndpointGatewayOptions.Builder() .id(id) .build(); Response<EndpointGateway> response = service.getEndpointGateway(getEndpointGatewayOptions).execute(); EndpointGateway endpointGateway = response.getResult();
const response = await vpcService.getEndpointGateway({ id });
response = service.get_endpoint_gateway(id) if response.status_code == 200: endpoint_gateway = response.get_result()
Response
Indicates whether to allow DNS resolution for this endpoint gateway when the VPC this endpoint gateway resides in has a DNS resolution binding to a VPC with
dns.enable_hub
set totrue
.The date and time that the endpoint gateway was created.
The CRN for this endpoint gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this endpoint gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this endpoint gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reserved IPs bound to this endpoint gateway.
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the endpoint gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this endpoint gateway. The name is unique across all endpoint gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-endpoint-gateway
The resource group for this endpoint gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
endpoint_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this endpoint gateway.
Possible values: number of items ≥ 0, contains only unique items
The fully qualified domain names for the target service.
The target for this endpoint gateway.
The VPC this endpoint gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The fully qualified domain name for the target service
Example:
my-cloudant-instance.appdomain.cloud
Status Code
The endpoint gateway was retrieved successfully.
An endpoint gateway with the specified identifier could not be found.
{ "allow_dns_resolution_binding": true, "created_at": "2020-07-24T19:42:46Z", "crn": "crn:[...]", "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "ips": [ { "address": "10.240.0.7", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0716-bb7e061d-7259-45b6-a0da-416ace665269", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-endpoint-gateway-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "endpoint_gateway", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "service_endpoints": [ "time.adn.networklayer.com" ], "target": { "name": "ibm-ntp-server", "resource_type": "provider_infrastructure_service" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "name": "my-vpc", "resource_type": "vpc" } }
Update an endpoint gateway
This request updates an endpoint gateway's name.
PATCH /endpoint_gateways/{id}
Request
Path Parameters
The endpoint gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The endpoint gateway patch
Indicates whether to allow DNS resolution for this endpoint gateway when the VPC this endpoint gateway resides in has a DNS resolution binding to a VPC with
dns.enable_hub
set totrue
.Must be
true
if the VPC this endpoint gateway resides in hasdns.enable_hub
set totrue
.The name for this endpoint gateway. The name must not be used by another endpoint gateway in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-endpoint-gateway
curl -X PATCH "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-endpoint-gateway-1-updated" }'
options := &vpcv1.UpdateEndpointGatewayOptions{ EndpointGatewayID: &id, Name: &name, } endpointGateway, response, err := vpcService.UpdateEndpointGateway(options)
UpdateEndpointGatewayOptions updateEndpointGatewayOptions = new UpdateEndpointGatewayOptions.Builder() .id(id) .name("my-endpoint-gateway") .build(); Response<EndpointGateway> response = service.updateEndpointGateway(updateEndpointGatewayOptions).execute(); EndpointGateway endpointGateway = response.getResult();
const response = await vpcService.updateEndpointGateway({ id, name: 'my-endpoint-gateway' });
new_name = 'my-endpoint-gateway-updated' response = service.update_endpoint_gateway(id, name=new_name)
Response
Indicates whether to allow DNS resolution for this endpoint gateway when the VPC this endpoint gateway resides in has a DNS resolution binding to a VPC with
dns.enable_hub
set totrue
.The date and time that the endpoint gateway was created.
The CRN for this endpoint gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::endpoint-gateway:r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Example:
ok
The URL for this endpoint gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The unique identifier for this endpoint gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-d7cc5196-9864-48c4-82d8-3f30da41fcc5
The reserved IPs bound to this endpoint gateway.
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the endpoint gateway.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this endpoint gateway. The name is unique across all endpoint gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-endpoint-gateway
The resource group for this endpoint gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
endpoint_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this endpoint gateway.
Possible values: number of items ≥ 0, contains only unique items
The fully qualified domain names for the target service.
The target for this endpoint gateway.
The VPC this endpoint gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
The fully qualified domain name for the target service
Example:
my-cloudant-instance.appdomain.cloud
Status Code
The endpoint gateway was updated successfully.
An invalid endpoint gateway patch was provided.
A VPC with the specified identifier could not be found.
The endpoint gateway patch object specified an
allow_dns_resolution_binding
value that conflicts with thedns.enable_hub
value of the VPC this endpoint gateway resides in.
{ "allow_dns_resolution_binding": true, "created_at": "2020-07-24T19:42:46Z", "crn": "crn:[...]", "health_state": "ok", "href": "https://us-south.iaas.cloud.ibm.com/v1/endpoint_gateways/r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "id": "r134-a4841334-b584-4293-938e-3bc63b4a5b6a", "ips": [ { "address": "10.240.0.7", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/0716-b28a7e6d-a66b-4de7-8713-15dcffdce401/reserved_ips/0716-bb7e061d-7259-45b6-a0da-416ace665269", "id": "0716-bb7e061d-7259-45b6-a0da-416ace665269", "lifecycle_state": "stable", "name": "my-reserved-ip-1", "resource_type": "subnet_reserved_ip" } ], "lifecycle_reasons": [], "lifecycle_state": "stable", "name": "my-endpoint-gateway-1-updated", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "resource_type": "endpoint_gateway", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:be5df5ca-12a0-494b-907e-aa6ec2bfa271", "href": "https://us-south.iaas.cloud.ibm.com/v1/security_groups/be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "service_endpoints": [ "time.adn.networklayer.com" ], "target": { "name": "ibm-ntp-server", "resource_type": "provider_infrastructure_service" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "name": "my-vpc", "resource_type": "vpc" } }
List all flow log collectors
This request lists all flow log collectors in the region. A flow log collector summarizes data sent over the instance network interfaces and instance network attachments contained within its target.
GET /flow_log_collectors
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
name
property matching the exact specified name.Filters the collection to resources with a
vpc.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
vpc.crn
property matching the specified CRN.Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:4727d842-f94f-4a2d-824a-9bc9b02c523b
Filters the collection to resources with a
vpc.name
property matching the exact specified name.Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
Filters the collection to resources with a
target.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Filters the collection to resources with a
target.resource_type
property matching the specified value.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_api_endpoint/v1/flow_log_collectors?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.ListFlowLogCollectorsOptions{} flowLogs, response, err = vpcService.ListFlowLogCollectors(options)
ListFlowLogCollectorsOptions listFlowLogCollectorsOptions = new ListFlowLogCollectorsOptions.Builder() .limit(Long.valueOf("10")) .build(); Response<FlowLogCollectorCollection> response = service.listFlowLogCollectors(listFlowLogCollectorsOptions).execute(); FlowLogCollectorCollection flowLogCollectorCollectionResult = response.getResult();
const response = await vpcService.listFlowLogCollectors();
response = service.list_flow_log_collectors()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors?limit=20
first
Collection of flow log collectors
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The flow log collectors were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors?limit=50" }, "flow_log_collectors": [ { "active": true, "auto_delete": true, "created_at": "2019-06-28T12:08:05Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:4dd1852a-3373-46c0-9240-f9c7f0d0c1a3", "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/4dd1852a-3373-46c0-9240-f9c7f0d0c1a3", "id": "4dd1852a-3373-46c0-9240-f9c7f0d0c1a3", "lifecycle_state": "pending", "name": "my-flow-log-collector-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" }, "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "name": "my-network-interface-1", "resource_type": "network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } }, { "active": true, "auto_delete": true, "created_at": "2019-06-19T12:08:05Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:64580c28-713a-4cda-9993-53bc6a529bb4", "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/64580c28-713a-4cda-9993-53bc6a529bb4", "id": "64580c28-713a-4cda-9993-53bc6a529bb4", "lifecycle_state": "stable", "name": "my-flow-log-collector-2", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" }, "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/8722d01c-9c78-4555-82b5-53ad1266f959", "id": "8722d01c-9c78-4555-82b5-53ad1266f959", "name": "my-subnet-1", "resource_type": "subnet" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } } ], "limit": 50, "total_count": 2 }
Create a flow log collector
This request creates and starts a new flow log collector from a flow log collector prototype object. The prototype object is structured in the same way as a retrieved flow log collector, and contains the information necessary to create and start the new flow log collector.
POST /flow_log_collectors
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.flow-log-collector.flow-log-collector.create
is.flow-log-collector.flow-log-collector.attach
is.instance.instance.attach
Generated when
target
specifies a virtual server instanceis.instance.network-attachment.attach
Generated when
target
specifies an instance network attachmentis.instance.network-interface.attach
Generated when
target
specifies an instance network interfaceis.subnet.subnet.attach
Generated when
target
specifies a subnetis.virtual-network-interface.virtual-network-interface.attach
Generated when
target
specifies a virtual network interfaceis.vpc.vpc.attach
Generated when
target
specifies a VPC
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The flow log collector prototype object
The Cloud Object Storage bucket where the collected flows will be logged. The bucket must exist and an IAM service authorization must grant
IBM Cloud Flow Logs
resources ofVPC Infrastructure Services
writer access to the bucket. For more information, see Creating a flow log collector.Examples:ViewThe globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The target this collector will collect flow logs for.
If the target is an instance, subnet, or VPC, flow logs will not be collected for any instance network attachments, virtual network interfaces or instance network interfaces within the target that are themselves the target of a more specific flow log collector.
The target must not be a virtual network interface that is attached to a bare metal server network attachment or to a file share mount target.
target
Indicates whether this collector will be active upon creation.
Default:
true
The name for this flow log collector. The name must not be used by another flow log collector in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-flow-log-collector
The resource group to use. If unspecified, the account's default resource group will be used.
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
resource_group
curl -X POST "$vpc_api_endpoint/v1/flow_log_collectors?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-flow-log-collector-1", "target": { "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" } }'
options := &vpcv1.CreateFlowLogCollectorOptions{} options.SetName(name) options.SetTarget(&vpcv1.FlowLogCollectorPrototypeTargetVPCIdentity{ ID: &vpcId, }) options.SetStorageBucket(&vpcv1.CloudObjectStorageBucketIdentity{ Name: &bucketName, }) flowLog, response, err = vpcService.CreateFlowLogCollector(options)
CloudObjectStorageBucketIdentityByName cloudObjectStorageBucketIdentityModel = new CloudObjectStorageBucketIdentityByName.Builder() .name(cosBucketName) .build(); FlowLogCollectorPrototypeTargetNetworkInterfaceIdentityNetworkInterfaceIdentityNetworkInterfaceIdentityById flowLogCollectorPrototypeTargetModel = new FlowLogCollectorPrototypeTargetNetworkInterfaceIdentityNetworkInterfaceIdentityNetworkInterfaceIdentityById.Builder() .id(targetNetworkInterfaceId) .build(); CreateFlowLogCollectorOptions createFlowLogCollectorOptions = new CreateFlowLogCollectorOptions.Builder() .storageBucket(cloudObjectStorageBucketIdentityModel) .target(flowLogCollectorPrototypeTargetModel) .name("my-flow-log-collector") .build(); Response<FlowLogCollector> response = service.createFlowLogCollector(createFlowLogCollectorOptions).execute(); FlowLogCollector flowLogCollectorResult = response.getResult();
const cloudObjectStorageBucketIdentityModel = { name: bucketName, }; const flowLogCollectorPrototypeTargetModel = { id: subnetID }; const params = { storageBucket: cloudObjectStorageBucketIdentityModel, target: flowLogCollectorPrototypeTargetModel, name: 'my-flow-log-collector', }; const response = await vpcService.createFlowLogCollector(params);
cloud_object_storage_bucket_identity_model = {} cloud_object_storage_bucket_identity_model['name'] = my-cos-bucket flow_log_collector_prototype_target_model = {} flow_log_collector_prototype_target_model['id'] = target_id resource_group_identity_model = {} resource_group_identity_model['id'] = resource_group_id storage_bucket = cloud_object_storage_bucket_identity_model target = flow_log_collector_prototype_target_model active = False name = 'my-flow-log-collector' resource_group = resource_group_identity_model response = service.create_flow_log_collector( storage_bucket, target, active=active, name=name, resource_group=resource_group, )
Response
Indicates whether this collector is active.
Example:
true
Indicates whether this flow log collector will be automatically deleted when
target
is deleted. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
The date and time that the flow log collector was created
The CRN for this flow log collector
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this flow log collector
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this flow log collector
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The lifecycle state of the flow log collector
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this flow log collector. The name is unique across all flow log collectors in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-flow-log-collector
The resource group for this flow log collector
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The Cloud Object Storage bucket where the collected flows are logged. For more information, see Viewing flow log objects.
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The target this collector is collecting flow logs for.
- If the target is an instance network attachment, flow logs will be collected for that instance network attachment.
- If the target is an instance network interface, flow logs will be collected for that instance network interface.
- If the target is a virtual network interface, flow logs will be collected for the
virtual network interface's
target
resource if the resource is an instance network attachment, unless the target resource is itself the target of a flow log collector. - If the target is a virtual server instance, flow logs will be collected for all network attachments or network interfaces on that instance.
- If the target is a subnet, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to that subnet.
- If the target is a VPC, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to all subnets within that VPC.
If the target is an instance, subnet, or VPC, flow logs will not be collected for any instance network attachments or instance network interfaces within the target that are themselves the target of a more specific flow log collector.
The VPC this flow log collector resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The flow log collector was created successfully.
An invalid flow log collector prototype object was provided.
The specified target is in use by another flow log collector.
{ "active": true, "auto_delete": true, "created_at": "2019-01-28T12:08:05Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "lifecycle_state": "pending", "name": "my-flow-log-collector-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" }, "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "name": "my-network-interface-1", "resource_type": "network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } }
Delete a flow log collector
This request stops and deletes a flow log collector. This operation cannot be reversed.
Collected flow logs remain available within the flow log collector's Cloud Object Storage bucket.
DELETE /flow_log_collectors/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.flow-log-collector.flow-log-collector.delete
is.flow-log-collector.flow-log-collector.detach
is.instance.instance.detach
Generated for a flow log collector that was attached to an instance
is.instance.network-interface.detach
Generated for a flow log collector that was attached to an instance network interface
is.instance.network-attachment.detach
Generated for a flow log collector that was attached to an instance network attachment
is.subnet.subnet.detach
Generated for a flow log collector that was attached to a subnet
is.virtual-network-interface.virtual-network-interface.detach
Generated for a flow log collector that was attached to a virtual network interface
is.vpc.vpc.detach
Generated for a flow log collector that was attached to a VPC
Request
Path Parameters
The flow log collector identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/flow_log_collectors/$flow_log_collector_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.DeleteFlowLogCollectorOptions{} options.SetID(id) response, err = vpcService.DeleteFlowLogCollector(options)
DeleteFlowLogCollectorOptions deleteFlowLogCollectorOptions = new DeleteFlowLogCollectorOptions.Builder() .id(id) .build(); Response<Void> response = service.deleteFlowLogCollector(deleteFlowLogCollectorOptions).execute();
const response = await vpcService.deleteFlowLogCollector({ id });
response = service.delete_flow_log_collector(id)
Retrieve a flow log collector
This request retrieves a single flow log collector specified by the identifier in the URL.
GET /flow_log_collectors/{id}
Request
Path Parameters
The flow log collector identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/flow_log_collectors/$flow_log_collector_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := &vpcv1.GetFlowLogCollectorOptions{} options.SetID(id) flowLog, response, err = vpcService.GetFlowLogCollector(options)
GetFlowLogCollectorOptions getFlowLogCollectorOptions = new GetFlowLogCollectorOptions.Builder() .id(id) .build(); Response<FlowLogCollector> response = service.getFlowLogCollector(getFlowLogCollectorOptions).execute(); FlowLogCollector flowLogCollectorResult = response.getResult();
const response = await vpcService.getFlowLogCollector({ id });
response = service.get_flow_log_collector(id)
Response
Indicates whether this collector is active.
Example:
true
Indicates whether this flow log collector will be automatically deleted when
target
is deleted. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
The date and time that the flow log collector was created
The CRN for this flow log collector
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this flow log collector
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this flow log collector
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The lifecycle state of the flow log collector
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this flow log collector. The name is unique across all flow log collectors in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-flow-log-collector
The resource group for this flow log collector
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The Cloud Object Storage bucket where the collected flows are logged. For more information, see Viewing flow log objects.
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The target this collector is collecting flow logs for.
- If the target is an instance network attachment, flow logs will be collected for that instance network attachment.
- If the target is an instance network interface, flow logs will be collected for that instance network interface.
- If the target is a virtual network interface, flow logs will be collected for the
virtual network interface's
target
resource if the resource is an instance network attachment, unless the target resource is itself the target of a flow log collector. - If the target is a virtual server instance, flow logs will be collected for all network attachments or network interfaces on that instance.
- If the target is a subnet, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to that subnet.
- If the target is a VPC, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to all subnets within that VPC.
If the target is an instance, subnet, or VPC, flow logs will not be collected for any instance network attachments or instance network interfaces within the target that are themselves the target of a more specific flow log collector.
The VPC this flow log collector resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The flow log collector was retrieved successfully.
The specified flow log collector could not be found.
{ "active": true, "auto_delete": true, "created_at": "2019-01-28T12:08:05Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "lifecycle_state": "pending", "name": "my-flow-log-collector-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" }, "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "name": "my-network-interface-1", "resource_type": "network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } }
Update a flow log collector
This request updates a flow log collector with the information in a provided flow log collector patch. The flow log collector patch object is structured in the same way as a retrieved flow log collector and contains only the information to be updated.
PATCH /flow_log_collectors/{id}
Request
Path Parameters
The flow log collector identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The flow log collector patch
Indicates whether this collector is active. Updating to false deactivates the collector and updating to true activates the collector.
Example:
true
The name for this flow log collector. The name must not be used by another flow log collector in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-flow-log-collector
curl -X PATCH "$vpc_api_endpoint/v1/flow_log_collectors/$flow_log_collector_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name":"my-flow-log-collector-1" }'
options := &vpcv1.UpdateFlowLogCollectorOptions{} options.SetID(id) options.SetName(name) flowLog, response, err = vpcService.UpdateFlowLogCollector(options)
UpdateFlowLogCollectorOptions updateFlowLogCollectorOptions = new UpdateFlowLogCollectorOptions.Builder() .id(id) .name("my-flow-log-collector") .active(true) .build(); Response<FlowLogCollector> response = service.updateFlowLogCollector(updateFlowLogCollectorOptions).execute(); FlowLogCollector flowLogCollectorResult = response.getResult();
const response = await vpcService.updateFlowLogCollector({ id, name: 'my-flow-log-collector', });
response = service.update_flow_log_collector(id, active=True, name='my-flow-log-collector')
Response
Indicates whether this collector is active.
Example:
true
Indicates whether this flow log collector will be automatically deleted when
target
is deleted. At present, this is alwaystrue
, but may be modifiable in the future.Example:
true
The date and time that the flow log collector was created
The CRN for this flow log collector
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:39300233-9995-4806-89a5-3c1b6eb88689
The URL for this flow log collector
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/39300233-9995-4806-89a5-3c1b6eb88689
The unique identifier for this flow log collector
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
39300233-9995-4806-89a5-3c1b6eb88689
The lifecycle state of the flow log collector
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The name for this flow log collector. The name is unique across all flow log collectors in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-flow-log-collector
The resource group for this flow log collector
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The Cloud Object Storage bucket where the collected flows are logged. For more information, see Viewing flow log objects.
The globally unique name of this Cloud Object Storage bucket
Possible values: 3 ≤ length ≤ 63, Value must match regular expression
^[a-z0-9]{1}[-a-z0-9]{1,61}[a-z0-9]{1}$
Example:
bucket-27200-lwx4cfvcue
storage_bucket
The target this collector is collecting flow logs for.
- If the target is an instance network attachment, flow logs will be collected for that instance network attachment.
- If the target is an instance network interface, flow logs will be collected for that instance network interface.
- If the target is a virtual network interface, flow logs will be collected for the
virtual network interface's
target
resource if the resource is an instance network attachment, unless the target resource is itself the target of a flow log collector. - If the target is a virtual server instance, flow logs will be collected for all network attachments or network interfaces on that instance.
- If the target is a subnet, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to that subnet.
- If the target is a VPC, flow logs will be collected for all instance network interfaces and virtual network interfaces attached to all subnets within that VPC.
If the target is an instance, subnet, or VPC, flow logs will not be collected for any instance network attachments or instance network interfaces within the target that are themselves the target of a more specific flow log collector.
The VPC this flow log collector resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Status Code
The flow log collector was updated successfully.
An invalid flow log collector patch was provided.
A flow log collector with the specified identifier could not be found.
{ "active": true, "auto_delete": true, "created_at": "2019-01-28T04:05:48Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::flow-log-collector:ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "href": "https://us-south.iaas.cloud.ibm.com/v1/flow_log_collectors/ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80", "lifecycle_state": "stable", "name": "my-flow-log-collector-1", "resource_group": { "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/4bbce614c13444cd8fc5e7e878ef8e21", "id": "4bbce614c13444cd8fc5e7e878ef8e21", "name": "Default" }, "storage_bucket": { "name": "bucket-27200-lwx4cfvcue" }, "target": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/1e09281b-f177-46fb-baf1-bc152b2e391a/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32", "name": "my-network-interface-1", "resource_type": "network_interface" }, "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/e2cd90a7-8c7c-476f-b454-9ea0b5387677", "id": "e2cd90a7-8c7c-476f-b454-9ea0b5387677", "name": "my-vpc", "resource_type": "vpc" } }
List all private path service gateways
This request lists all private path service gateways. Private path service gateways allow service providers to make their services available to other accounts, using private path connectivity.
The private path service gateways will be sorted by their created_at
property values,
with newest private path service gateways first. Private path service gateways with
identical created_at
property values will in turn be sorted by ascending name
property
values.
GET /private_path_service_gateways
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with a
resource_group.id
property matching the specified identifier.Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
curl -X GET "$vpc_api_endpoint/v1/private_path_service_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewListPrivatePathServiceGatewaysOptions() privatePathServiceGateways, response, err := vpcService.ListPrivatePathServiceGateways(options)
ListPrivatePathServiceGatewaysOptions listPrivatePathServiceGatewaysOptions = new ListPrivatePathServiceGatewaysOptions.Builder() .build(); Response<PrivatePathServiceGatewayCollection> response = service.listPrivatePathServiceGateways(listPrivatePathServiceGatewaysOptions).execute(); PrivatePathServiceGatewayCollection privatePathServiceGatewayCollection = response.getResult();
const response = await vpcService.listPrivatePathServiceGateways();
response = service.list_private_path_service_gateways()
Response
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
Collection of private path service gateways
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways?start=9d5a91a3e2cbd233b5a5b33436855ed1&limit=20
next
Status Code
The private path service gateways were retrieved successfully.
{ "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways?limit=50" }, "limit": 50, "private_path_service_gateways": [ { "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "default_access_policy": "permit", "endpoint_gateways_count": 2, "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "lifecycle_state": "stable", "load_balancer": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r134-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-load-balancer", "resource_type": "load_balancer" }, "name": "my-private-path-service-gateway", "published": true, "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "private_path_service_gateway", "service_endpoints": [ "my-service.example.com" ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zonal_affinity": true } ], "total_count": 1 }
Create a private path service gateway
This request creates a private path service gateway from a private path service gateway prototype object. The prototype object is structured in the same way as a retrieved private path service gateway, and contains the information necessary to create the new private path service gateway.
POST /private_path_service_gateways
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The private path service gateway prototype
The load balancer for this private path service gateway. The load balancer must have
is_private_path
set totrue
.The private path service gateway will reside in the same VPC as the specified load balancer.
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
load_balancer
The fully qualified domain names for this private path service gateway. Any uppercase letters will be converted to lowercase.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, 4 ≤ length ≤ 255, Value must match regular expression
^((?=[A-Za-z0-9-]{1,63}\.)[A-Za-z0-9-]*\.)+[A-Za-z]{2,63}\.?$
The policy to use for bindings from accounts without an explicit account policy.
Allowable values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Default:
deny
The name for this private path service gateway. The name must not be used by another private path service gateway in the VPC. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
The resource group to use. If unspecified, the account's default resource group will be used.
Indicates whether this private path service gateway has zonal affinity.
true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
Default:
false
curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "name": "my-private-path-service-gateway", "service_endpoints": ["example.com"], "load_balancer": {"crn": "crn:[...]"} }'
options := &vpcv1.CreatePrivatePathServiceGatewayOptions{} options.SetName(name) options.SetServiceEndpoints(&[]string{"example.com"}[0]) options.SetLoadBalancer(&vpcv1.LoadBalancerIdentity{ Crn: loadBalancerCrn, }) privatePathServiceGateway, response, err = vpcService.CreatePrivatePathServiceGateway(options)
LoadBalancerIdentityById lbIdentityModel = new LoadBalancerIdentityById.Builder() .id(lbId) .build(); PrivatePathServiceGatewayPrototype privatePathServiceGatewayPrototypeModel = new PrivatePathServiceGatewayPrototype.Builder() .loadBalancer(lbIdentityModel) .name("my-private-path-service-gateway") .serviceEndpoints(new String[]{"example.com"}) .build(); CreatePrivatePathServiceGatewayOptions createPrivatePathServiceGatewayOptions = new CreatePrivatePathServiceGatewayOptions.Builder() .PrivatePathServiceGatewayPrototype(privatePathServiceGatewayPrototypeModel) .build(); Response<PrivatePathServiceGateway> response = service.createPrivatePathServiceGateway(createPrivatePathServiceGatewayOptions).execute(); PrivatePathServiceGateway privatePathServiceGateway = response.getResult();
const lbIdentityModel = { id: lbID, }; const privatePathServiceGatewayPrototypeModel = { name: 'my-private-path-service-gateway', load_balancer: lbIdentityModel, service_endpoints: ["example.com"], }; const params = { privatePathServiceGatewayPrototype: privatePathServiceGatewayPrototypeModel, }; const response = await vpcService.createPrivatePathServiceGateway(params);
load_balancer_identity_model = {} private_path_service_gateway_prototype_model = {} private_path_service_gateway_prototype_model['load_balancer'] = load_balancer_identity_model private_path_service_gateway_prototype_model['name'] = 'my-private-path-service-gateway' private_path_service_gateway_prototype_model['service_endpoints'] = ["example.com"] private_path_service_gateway_prototype = private_path_service_gateway_prototype_model response = service.create_private_path_service_gateway(private_path_service_gateway_prototype)
Response
The date and time that the private path service gateway was created
The CRN for this private path service gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::private-path-service-gateway:r134-fb880975-db45-4459-8548-64e3995ac213
The policy to use for bindings from accounts without an explicit account policy.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The number of active endpoint gateways using this private path service gateway.
Possible values: value ≥ 0
The URL for this private path service gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213
The unique identifier for this private path service gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The lifecycle state of the private path service gateway
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The load balancer for this private path service gateway.
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer
The name for this private path service gateway. The name is unique across all private path service gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
Indicates the availability of this private path service gateway
true
: Any account can request access to this private path service gateway.false
: Access is restricted to the account that created this private path service gateway.
The resource group for this private path service gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
private_path_service_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The fully qualified domain names for this private path service gateway.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, 4 ≤ length ≤ 255, Value must match regular expression
^((?=[A-Za-z0-9-]{1,63}\.)[A-Za-z0-9-]*\.)+[A-Za-z]{2,63}\.?$
The VPC this private path service gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Indicates whether this private path service gateway has zonal affinity.
true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
Status Code
The private path service gateway was created successfully.
An invalid private path service gateway prototype object was provided.
{ "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "default_access_policy": "permit", "endpoint_gateways_count": 2, "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "lifecycle_state": "pending", "load_balancer": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r134-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-load-balancer", "resource_type": "load_balancer" }, "name": "my-private-path-service-gateway", "published": true, "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "private_path_service_gateway", "service_endpoints": [ "my-service.example.com" ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zonal_affinity": true }
Delete a private path service gateway
This request deletes a private path service gateway. For this request to succeed, the
value of endpoint_gateway_count
must be 0
. This operation cannot be reversed.
DELETE /private_path_service_gateways/{id}
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X DELETE "$vpc_api_endpoint/v1/private_path_service_gateways/$private_path_service_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewDeletePrivatePathServiceGatewayOptions(id) response, err := vpcService.DeletePrivatePathServiceGateway(options)
DeletePrivatePathServiceGatewayOptions deletePrivatePathServiceGatewayOptions = new DeletePrivatePathServiceGatewayOptions.Builder() .id(id) .build(); Response<Void> response = service.deletePrivatePathServiceGateway(deletePrivatePathServiceGatewayOptions).execute();
const response = await vpcService.deletePrivatePathServiceGateway({ id });
response = service.delete_private_path_service_gateway(id)
Response
The date and time that the private path service gateway was created
The CRN for this private path service gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::private-path-service-gateway:r134-fb880975-db45-4459-8548-64e3995ac213
The policy to use for bindings from accounts without an explicit account policy.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The number of active endpoint gateways using this private path service gateway.
Possible values: value ≥ 0
The URL for this private path service gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213
The unique identifier for this private path service gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The lifecycle state of the private path service gateway
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The load balancer for this private path service gateway.
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer
The name for this private path service gateway. The name is unique across all private path service gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
Indicates the availability of this private path service gateway
true
: Any account can request access to this private path service gateway.false
: Access is restricted to the account that created this private path service gateway.
The resource group for this private path service gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
private_path_service_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The fully qualified domain names for this private path service gateway.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, 4 ≤ length ≤ 255, Value must match regular expression
^((?=[A-Za-z0-9-]{1,63}\.)[A-Za-z0-9-]*\.)+[A-Za-z]{2,63}\.?$
The VPC this private path service gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Indicates whether this private path service gateway has zonal affinity.
true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
Status Code
The private path service gateway deletion request was accepted.
A private path service gateway with the specified identifier could not be found.
The private path service gateway is in use and cannot be deleted.
{ "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "default_access_policy": "permit", "endpoint_gateways_count": 2, "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "lifecycle_state": "deleting", "load_balancer": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r134-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-load-balancer", "resource_type": "load_balancer" }, "name": "my-private-path-service-gateway", "published": true, "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "private_path_service_gateway", "service_endpoints": [ "my-service.example.com" ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zonal_affinity": true }
Retrieve a private path service gateway
This request retrieves the private path service gateway specified by the identifier in the URL.
GET /private_path_service_gateways/{id}
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
curl -X GET "$vpc_api_endpoint/v1/private_path_service_gateways/$private_path_service_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
options := vpcService.NewGetPrivatePathServiceGatewayOptions(id) privatePathServiceGateway, response, err := vpcService.GetPrivatePathServiceGateway(options)
GetPrivatePathServiceGatewayOptions getPrivatePathServiceGatewayOptions = new GetPrivatePathServiceGatewayOptions.Builder() .id(id) .build(); Response<PrivatePathServiceGateway> response = service.getPrivatePathServiceGateway(getPrivatePathServiceGatewayOptions).execute(); PrivatePathServiceGateway privatePathServiceGateway = response.getResult();
const response = await vpcService.getPrivatePathServiceGateway({ id });
response = service.get_private_path_service_gateway(id)
Response
The date and time that the private path service gateway was created
The CRN for this private path service gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::private-path-service-gateway:r134-fb880975-db45-4459-8548-64e3995ac213
The policy to use for bindings from accounts without an explicit account policy.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The number of active endpoint gateways using this private path service gateway.
Possible values: value ≥ 0
The URL for this private path service gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213
The unique identifier for this private path service gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The lifecycle state of the private path service gateway
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The load balancer for this private path service gateway.
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer
The name for this private path service gateway. The name is unique across all private path service gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
Indicates the availability of this private path service gateway
true
: Any account can request access to this private path service gateway.false
: Access is restricted to the account that created this private path service gateway.
The resource group for this private path service gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
private_path_service_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The fully qualified domain names for this private path service gateway.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, 4 ≤ length ≤ 255, Value must match regular expression
^((?=[A-Za-z0-9-]{1,63}\.)[A-Za-z0-9-]*\.)+[A-Za-z]{2,63}\.?$
The VPC this private path service gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Indicates whether this private path service gateway has zonal affinity.
true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
Status Code
The private path service gateway was retrieved successfully.
A private path service gateway with the specified identifier could not be found.
{ "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "default_access_policy": "permit", "endpoint_gateways_count": 2, "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "lifecycle_state": "stable", "load_balancer": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r134-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-load-balancer", "resource_type": "load_balancer" }, "name": "my-private-path-service-gateway", "published": true, "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "private_path_service_gateway", "service_endpoints": [ "my-service.example.com" ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zonal_affinity": true }
Update a private path service gateway
This request updates a private path service gateway with the information provided in a private path service gateway patch object. The private path service gateway patch object is structured in the same way as a retrieved private path service gateway and contains only the information to be updated.
PATCH /private_path_service_gateways/{id}
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.private-path-service-gateway.private-path-service-gateway.update
is.private-path-service-gateway.load-balancer.detach
Generated for the outgoing load balancer when
load_balancer
is updated.is.load-balancer.private-path-service-gateway.detach
Generated for the outgoing load balancer when
load_balancer
is updated.is.private-path-service-gateway.load-balancer.attach
Generated for the new load balancer when
load_balancer
is updated.is.load-balancer.private-path-service-gateway.attach
Generated for the new load balancer when
load_balancer
is updated.is.private-path-service-gateway.private-path-service-gateway.publish
Generated when
published
is set totrue
.is.private-path-service-gateway.private-path-service-gateway.unpublish
Generated when
published
is set tofalse
.is.private-path-service-gateway.private-path-service-gateway.revoke-account
Generated for each account that has associated endpoint gateway binding when
published
is set tofalse
.is.private-path-service-gateway.endpoint-gateway-binding.deny
Generated when
published
is set tofalse
.
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The private path service gateway patch.
The policy to use for bindings from accounts without an explicit account policy.
- Updating to
review
sets the status of any future endpoint gateway bindings topending
. - Updating to
permit
updates both the status of anypending
and future endpoint gateway bindings topermitted
. - Updating to
deny
updates both the status of anypending
and future endpoint gateway bindings todenied
.
Allowable values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
- Updating to
The load balancer for this private path service gateway. The load balancer must have
is_private_path
set totrue
, and must be in the same VPC as the private path service gateway.The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
load_balancer
The name for this private path service gateway. The name must not be used by another private path service gateway in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
Indicates the availability of this private path service gateway
true
: Any account can request access to this private path service gateway.false
: Access is restricted to the account that created this private path service gateway. Any existing access from other accounts will be revoked, and the associated endpoint gateways will have theirlifecycle_state
transition tofailed
.
Updating the value of
zonal_affinity
changes how traffic for existing and future endpoint gateway bindings will be routed:true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
curl -X PATCH "$vpc_api_endpoint/v1/private_path_service_gateways/$private_path_service_gateway_id?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "published": true }'
options := &vpcv1.UpdatePrivatePathServiceGatewayOptions{ PrivatePathServiceGatewayID: &id, Name: &name, } privatePathServiceGateway, response, err := vpcService.UpdatePrivatePathServiceGateway(options)
UpdatePrivatePathServiceGatewayOptions updatePrivatePathServiceGatewayOptions = new UpdatePrivatePathServiceGatewayOptions.Builder() .id(id) .name(name) .build(); Response<PrivatePathServiceGateway> response = service.updatePrivatePathServiceGateway(updatePrivatePathServiceGatewayOptions).execute(); PrivatePathServiceGateway privatePathServiceGateway = response.getResult();
const response = await vpcService.updatePrivatePathServiceGateway({ id, name: 'my-private-path-service-gateway' });
name = "my-private-path-service-gateway" response = service.update_private_path_service_gateway( id, name=name, )
Response
The date and time that the private path service gateway was created
The CRN for this private path service gateway
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::private-path-service-gateway:r134-fb880975-db45-4459-8548-64e3995ac213
The policy to use for bindings from accounts without an explicit account policy.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The number of active endpoint gateways using this private path service gateway.
Possible values: value ≥ 0
The URL for this private path service gateway
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213
The unique identifier for this private path service gateway
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The lifecycle state of the private path service gateway
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The load balancer for this private path service gateway.
The load balancer's CRN
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::load-balancer:dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The load balancer's canonical URL.
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/load_balancers/dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The unique identifier for this load balancer
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
dd754295-e9e0-4c9d-bf6c-58fbc59e5727
The name for this load balancer. The name is unique across all load balancers in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-load-balancer
The resource type
Possible values: [
load_balancer
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
load_balancer
The name for this private path service gateway. The name is unique across all private path service gateways in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-private-path-service-gateway
Indicates the availability of this private path service gateway
true
: Any account can request access to this private path service gateway.false
: Access is restricted to the account that created this private path service gateway.
The resource group for this private path service gateway
Examples:ViewThe URL for this resource group
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://resource-controller.cloud.ibm.com/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
resource_group
The resource type
Possible values: [
private_path_service_gateway
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The fully qualified domain names for this private path service gateway.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, 4 ≤ length ≤ 255, Value must match regular expression
^((?=[A-Za-z0-9-]{1,63}\.)[A-Za-z0-9-]*\.)+[A-Za-z]{2,63}\.?$
The VPC this private path service gateway resides in
Examples:ViewThe CRN for this VPC
Possible values: 9 ≤ length ≤ 512
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The URL for this VPC
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/vpcs/r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Link to documentation about deleted resources
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://cloud.ibm.com/apidocs/vpc#deleted-resources
deleted
vpc
Indicates whether this private path service gateway has zonal affinity.
true
: Traffic to the service from a zone the service resides in will remain in that zone.false
: Traffic to the service from a zone will be load balanced across all zones in the region the service resides in.
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
Status Code
The private path service gateway was updated successfully.
An invalid private path service gateway patch was provided.
A private path service gateway with the specified identifier could not be found.
{ "created_at": "2019-01-28T11:59:46Z", "crn": "crn:[...]", "default_access_policy": "permit", "endpoint_gateways_count": 2, "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "id": "r134-d50a9a31-ec85-4442-a6a3-4b1b9da417f0", "lifecycle_state": "stable", "load_balancer": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/load_balancers/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "r134-a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-load-balancer", "resource_type": "load_balancer" }, "name": "my-private-path-service-gateway", "published": true, "resource_group": { "crn": "crn:v1:bluemix:public:resource-controller::a/aa2432b1fa4d4ace891e9b80fc104e34::resource-group:678523bcbe2b4eada913d32640909956", "href": "https://resource-controller.cloud.ibm.com/v2/resource_groups/678523bcbe2b4eada913d32640909956", "id": "678523bcbe2b4eada913d32640909956", "name": "Default" }, "resource_type": "private_path_service_gateway", "service_endpoints": [ "my-service.example.com" ], "vpc": { "crn": "crn:[...]", "href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs/r134-a0819609-0997-4f92-9409-86c95ddf59d3", "id": "a0819609-0997-4f92-9409-86c95ddf59d3", "name": "my-vpc", "resource_type": "vpc" }, "zonal_affinity": true }
List all account policies for a private path service gateway
This request lists all account policies for a private path service gateway. Each policy defines how requests to use the private path service gateway from that account will be handled.
The account policies will be sorted by their created_at
property values, with newest
account policies first. Account policies with identical created_at
property values will
in turn be sorted by ascending id
property values.
GET /private_path_service_gateways/{private_path_service_gateway_id}/account_policies
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to resources with an
account.id
property matching the specified identifier.Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
Response
Collection of account policies
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/65f30e48-3074-4eb0-9ec4-51ce2ec968eb/account_policies?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/65f30e48-3074-4eb0-9ec4-51ce2ec968eb/account_policies?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The account policies were retrieved successfully.
The specified private path service gateway could not be found.
{ "account_policies": [ { "access_policy": "permit", "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/account_policies/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "resource_type": "private_path_service_gateway_account_policy" } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-65f30e48-3074-4eb0-9ec4-51ce2ec968eb/account_policies?limit=20" }, "limit": 50, "total_count": 1 }
Create an account policy for a private path service gateway
This request creates an account policy from an account policy prototype object. The prototype object is structured in the same way as a retrieved account policy, and contains the information necessary to create the new account policy.
POST /private_path_service_gateways/{private_path_service_gateway_id}/account_policies
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The account policy prototype
The access policy for the account:
-
permit
: access will be permitted -
deny
: access will be denied -
review
: access will be manually reviewed -
Specifying
review
sets the status of future endpoint gateway bindings from this account topending
. -
Specifying
permit
updates both the status ofpending
and future endpoint gateway bindings from this account topermitted
. -
Specifying
deny
updates both the status ofpending
and future endpoint gateway bindings from this account todenied
.
Allowable values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
-
The account for this access policy. The account must be unique across all account policies for this private path service gateway.
Examples:ViewThe unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
account
Response
The access policy for the account:
- permit: access will be permitted
- deny: access will be denied
- review: access will be manually reviewed
The enumerated values for this property may expand in the future.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The account for this access policy.
The unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
The resource type
Possible values: [
account
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
account
The date and time that the account policy was created
The URL for this account policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213/account_policies/dd455384-b019-4242-9453-45fe68b18e4c
The unique identifier for this account policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The resource type
Possible values: [
private_path_service_gateway_account_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The account policy for the private path service gateway was created successfully.
An invalid account policy prototype object was provided.
The specified private path service gateway could not be found.
{ "access_policy": "permit", "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/account_policies/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "resource_type": "private_path_service_gateway_account_policy" }
Delete an account policy for a private path service gateway
This request deletes an account policy. This operation cannot be reversed.
DELETE /private_path_service_gateways/{private_path_service_gateway_id}/account_policies/{id}
Request
Path Parameters
The private path service gateway identifier
The account policy identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Retrieve an account policy for a private path service gateway
This request retrieves a single account policy specified by the identifier in the URL.
GET /private_path_service_gateways/{private_path_service_gateway_id}/account_policies/{id}
Request
Path Parameters
The private path service gateway identifier
The account policy identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Response
The access policy for the account:
- permit: access will be permitted
- deny: access will be denied
- review: access will be manually reviewed
The enumerated values for this property may expand in the future.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The account for this access policy.
The unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
The resource type
Possible values: [
account
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
account
The date and time that the account policy was created
The URL for this account policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213/account_policies/dd455384-b019-4242-9453-45fe68b18e4c
The unique identifier for this account policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The resource type
Possible values: [
private_path_service_gateway_account_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The account policy was retrieved successfully.
An account policy with the specified identifier could not be found.
{ "access_policy": "permit", "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/account_policies/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "resource_type": "private_path_service_gateway_account_policy" }
Update an account policy for a private path service gateway
This request updates an account policy with the information in a provided account policy patch. The account policy patch object is structured in the same way as a retrieved account policy and contains only the information to be updated.
PATCH /private_path_service_gateways/{private_path_service_gateway_id}/account_policies/{id}
Request
Path Parameters
The private path service gateway identifier
The account policy identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
The account policy patch
The access policy for the account:
-
permit: access will be permitted
-
deny: access will be denied
-
review: access will be manually reviewed
-
Updating to
review
sets the status of future endpoint gateway bindings from this account topending
. -
Updating to
permit
updates both the status of anypending
and future endpoint gateway bindings from this account topermitted
. -
Updating to
deny
updates both the status of anypending
and future endpoint gateway bindings from this account todenied
.
Allowable values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
-
Response
The access policy for the account:
- permit: access will be permitted
- deny: access will be denied
- review: access will be manually reviewed
The enumerated values for this property may expand in the future.
Possible values: [
deny
,permit
,review
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The account for this access policy.
The unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
The resource type
Possible values: [
account
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
account
The date and time that the account policy was created
The URL for this account policy
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213/account_policies/dd455384-b019-4242-9453-45fe68b18e4c
The unique identifier for this account policy
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-fb880975-db45-4459-8548-64e3995ac213
The resource type
Possible values: [
private_path_service_gateway_account_policy
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The account policy was updated successfully.
An invalid account policy patch was provided.
An account policy with the specified identifier could not be found.
{ "access_policy": "permit", "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/account_policies/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "resource_type": "private_path_service_gateway_account_policy" }
List all endpoint gateway bindings for a private path service gateway
This request lists all endpoint gateway bindings for a private path service gateway. Each
endpoint gateway binding is implicitly created when an endpoint gateway is created
targeting the private path service gateway. The associated account policy is applied to
all pending
endpoint gateway bindings. If an associated account policy doesn't exist,
the private path service gateway's default_access_policy
is used.
The endpoint gateway bindings will be sorted by their created_at
property values, with
newest endpoint gateway bindings first. Endpoint gateway bindings with identical
created_at
property values will in turn be sorted by ascending name
property values.
GET /private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]A server-provided token determining what resource to start the page on
The number of resources to return on a page
Possible values: 1 ≤ value ≤ 100
Default:
50
Filters the collection to endpoint gateway bindings with a
status
property matching the specified value.Allowable values: [
denied
,expired
,pending
,permitted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Filters the collection to resources with an
account.id
property matching the specified identifier.Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
Response
Collection of endpoint gateway bindings
A link to the first page of resources
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/65f30e48-3074-4eb0-9ec4-51ce2ec968eb/endpoint_gateway_bindings?limit=20
first
The maximum number of resources that can be returned by the request
Possible values: 1 ≤ value ≤ 100
Example:
20
The total number of resources across all pages
Possible values: value ≥ 0
Example:
132
A link to the next page of resources. This property is present for all pages except the last page
The URL for a page of resources
Possible values: Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/65f30e48-3074-4eb0-9ec4-51ce2ec968eb/endpoint_gateway_bindings?start=9d5a91a3e2cbd233b5a5b33436855ed&limit=20
next
Status Code
The endpoint gateway bindings were retrieved successfully.
The specified private path service gateway could not be found.
{ "endpoint_gateway_bindings": [ { "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "expiration_at": "2022-01-10T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/endpoint_gateway_bindings/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "lifecycle_state": "stable", "resource_type": "private_path_service_gateway_endpoint_gateway_binding", "status": "permitted" } ], "first": { "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-65f30e48-3074-4eb0-9ec4-51ce2ec968eb/endpoint_gateway_bindings?limit=20" }, "limit": 50, "total_count": 1 }
Retrieve an endpoint gateway binding for a private path service gateway
This request retrieves a single endpoint gateway binding specified by the identifier in the URL.
GET /private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/{id}
Request
Path Parameters
The private path service gateway identifier
The endpoint gateway binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Response
The account that created the endpoint gateway.
The unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
The resource type
Possible values: [
account
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
account
The date and time that the endpoint gateway binding was created
The URL for this endpoint gateway binding
Possible values: 10 ≤ length ≤ 8000, Value must match regular expression
^http(s)?:\/\/([^\/?#]*)([^?#]*)(\?([^#]*))?(#(.*))?$
Example:
https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-fb880975-db45-4459-8548-64e3995ac213/endpoint_gateway_bindings/r134-ce9dac18-dea0-4392-841c-142d3300674f
The unique identifier for this endpoint gateway binding
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r134-ce9dac18-dea0-4392-841c-142d3300674f
The lifecycle state of the endpoint gateway binding
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Example:
stable
The resource type
Possible values: [
private_path_service_gateway_endpoint_gateway_binding
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The status of the endpoint gateway binding:
denied
: endpoint gateway binding was deniedexpired
: endpoint gateway binding has expiredpending
: endpoint gateway binding is awaiting reviewpermitted
: endpoint gateway binding was permitted
An endpoint gateway binding will be automatically deleted when its associated endpoint gateway is deleted.
The enumerated values for this property may expand in the future.
Possible values: [
denied
,expired
,pending
,permitted
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The expiration date and time for the endpoint gateway binding. If the
status
ispermitted
ordenied
, the property will be absent.
Status Code
The endpoint gateway binding was retrieved successfully.
An endpoint gateway binding with the specified identifier could not be found.
{ "account": { "id": "aa2432b1fa4d4ace891e9b80fc104e34", "resource_type": "account" }, "created_at": "2022-01-07T16:56:54Z", "expiration_at": "2022-01-10T16:56:54Z", "href": "https://us-south.iaas.cloud.ibm.com/v1/private_path_service_gateways/r134-f64efe74-a5a2-45c7-b37d-5071d2dd6339/endpoint_gateway_bindings/r134-df760133-3513-47e7-b980-26cca666561b", "id": "r134-df760133-3513-47e7-b980-26cca666561b", "lifecycle_state": "stable", "resource_type": "private_path_service_gateway_endpoint_gateway_binding", "status": "permitted" }
Deny an endpoint gateway binding for a private path service gateway
This request denies a pending
endpoint gateway request, and optionally sets the policy
to deny future requests from the same account.
POST /private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/{id}/deny
Request
Path Parameters
The private path service gateway identifier
The endpoint gateway binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Options to control the deny operation.
Indicates whether this will become the access policy for any
pending
and future endpoint gateway bindings from the same account.If set to
true
:- If the account has an existing access policy, that policy will be updated to
deny
. Otherwise, a newdeny
access policy will be created for the account. - All
pending
endpoint gateway bindings for the account will be denied.
If set to
false
:- No access policies will be created or updated
- All
pending
endpoint gateway bindings for the account will remainpending
Default:
false
Example:
true
- If the account has an existing access policy, that policy will be updated to
curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/$id/deny?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d ''
options := &vpcv1.DenyPrivatePathServiceGatewayEndpointGatewayBindingOptions(private_path_service_gateway_id, id) options.SetSetAccountPolicy(true) response, err = vpcService.DenyPrivatePathServiceGatewayEndpointGatewayBinding(options)
DenyPrivatePathServiceGatewayEndpointGatewayBindingOptions denyPrivatePathServiceGatewayEndpointGatewayBindingOptions = new DenyPrivatePathServiceGatewayEndpointGatewayBindingOptions.Builder() .privatePathServiceGatewayId(privatePathServiceGatewayId) .setAccountPolicy(true) .build(); Response<Void> response = service.denyPrivatePathServiceGatewayEndpointGatewayBinding(denyPrivatePathServiceGatewayEndpointGatewayBindingOptions).execute();
const params = { setAccountPolicy: true, }; const response = await vpcService.denyPrivatePathServiceGatewayEndpointGatewayBinding(params);
response = service.deny_private_path_service_endpoint_gateway_binding( private_path_service_gateway_id, set_account_policy=true)
Permit an endpoint gateway binding for a private path service gateway
This request permits a pending
endpoint gateway request, and optionally sets the policy
to permit future requests from the same account.
POST /private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/{id}/permit
Request
Path Parameters
The private path service gateway identifier
The endpoint gateway binding identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Options to control the permit operation.
Indicates whether this will become the access policy for any
pending
and future endpoint gateway bindings from the same account.If set to
true
:- If the account has an existing access policy, that policy will be updated to
permit
. Otherwise, a newpermit
access policy will be created for the account. - All
pending
endpoint gateway bindings for the account will be permitted.
If set to
false
:- No access policies will be created or updated
- All
pending
endpoint gateway bindings for the account will remainpending
Default:
false
Example:
true
- If the account has an existing access policy, that policy will be updated to
curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/$id/permit?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d ''
options := &vpcv1.PermitPrivatePathServiceGatewayEndpointGatewayBindingOptions(private_path_service_gateway_id, id) options.SetSetAccountPolicy(true) response, err = vpcService.PermitPrivatePathServiceGatewayEndpointGatewayBinding(options)
PermitPrivatePathServiceGatewayEndpointGatewayBindingOptions permitPrivatePathServiceGatewayEndpointGatewayBindingOptions = new PermitPrivatePathServiceGatewayEndpointGatewayBindingOptions.Builder() .privatePathServiceGatewayId(privatePathServiceGatewayId) .setAccountPolicy(true) .build(); Response<Void> response = service.permitPrivatePathServiceGatewayEndpointGatewayBinding(permitEndpointGatewayBindingOptions).execute();
const params = { setAccountPolicy: true, }; const response = await vpcService.permitPrivatePathServiceGatewayEndpointGatewayBinding(params);
response = service.permit_private_path_service_endpoint_gateway_binding( private_path_service_gateway_id, set_account_policy=true)
Revoke access to a private path service gateway for an account
This request revokes a consumer account. This operation cannot be reversed. The status
of
all endpoint gateway bindings associated with the specified private path service gateway
become denied
. If the specified account has an existing access policy, that policy will be
updated to denied
. Otherwise, a new deny
access policy will be created for the account.
POST /private_path_service_gateways/{private_path_service_gateway_id}/revoke_account
Auditing
Calling this method generates the following auditing events, depending on any listed conditions.
is.private-path-service-gateway.private-path-service-gateway.revoke-account
is.private-path-service-gateway.endpoint-gateway-binding.deny
Generated for each associated endpoint gateway binding
is.private-path-service-gateway.account-policy.update
Generated when an account has an existing access policy
is.private-path-service-gateway.account-policy.create
Generated when an does not have an existing access policy
Request
Path Parameters
The private path service gateway identifier
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-04-30
and2024-04-30
.Possible values: length = 10, Value must match regular expression
^[0-9]{4}-[0-9]{2}-[0-9]{2}$
The infrastructure generation. For the API behavior documented here, specify
2
.Allowable values: [
2
]
Options to control the revoke operation.
The account that will be revoked access to the private path service gateway.
Examples:ViewThe unique identifier for this account
Possible values: Value must match regular expression
^[0-9a-f]{32}$
Example:
bb1b52262f7441a586f49068482f1e60
account
curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/revoke_account?version=2024-04-30&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token" -d '{ "account": {"id": "aa2432b1fa4d4ace891e9b80fc104e34"}}'
options := &vpcv1.RevokeAccountForPrivatePathServiceGatewayOptions(private_path_service_gateway_id) options.SetAccount(&vpcv1.AccountIdentity{ ID: &accountID, }) response, err = vpcService.RevokeAccountForPrivatePathServiceGateway(options)
AccountIdentityById accountIdentityModel = new AccountIdentityById.Builder() .id(lbId) .build(); RevokeAccountForPrivatePathServiceGatewayOptions revokeAccountForPrivatePathServiceGatewayOptions = new RevokeAccountForPrivatePathServiceGatewayOptions.Builder() .privatePathServiceGatewayId(privatePathServiceGatewayId) .account(accountIdentityModel) .requestPolicy("permit") .build(); Response<Void> response = service.revokeAccountForPrivatePathServiceGateway(revokeAccountForPrivatePathServiceGatewayOptions).execute();
const accountIdentityModel = { id: accountID, }; const params = { account: accountIdentityModel, }; const response = await vpcService.revokeAccountForPrivatePathServiceGateway(params);
account_identity_model = {} account_identity_model[ 'id'] = account_id response = service.revoke_account_for_private_path_service_gateway( private_path_service_gateway_id, account=account_identity_model)