IBM Cloud API Docs

Introduction to the beta VPC API

Last updated: 2024-04-16

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.

Related APIs

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.list

  • is.vpc.vpc.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.vpc.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • classic_access
    boolean

    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-16&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

Response Body

VPCCollection

Status Code

  • 200

    The VPCs were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.create

Auditing

Calling this method generates the following auditing event.

  • is.vpc.vpc.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

VPCPrototype

The VPC prototype object

  • curl -X POST "$vpc_api_endpoint/v1/vpcs?version=2024-04-16&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

Response Body

VPC

Status Code

  • 201

    The VPC was created successfully.

  • 400

    An invalid VPC prototype object was provided.

Example responses
  • {
  "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 is true, 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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.delete

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 to true was attached to the VPC

  • is.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-Match
    string

    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

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The VPC was deleted successfully.

  • 404

    A VPC with the specified identifier could not be found.

  • 409

    The VPC is in use and cannot be deleted.

  • 412

    The provided If-Match value does not match the current ETag value of the VPC.

No Sample Response

This method does not specify any sample responses.

Retrieve a VPC

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

GET /vpcs/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.vpc.read

Request

Path Parameters

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPC

Status Code

  • 200

    The VPC was retrieved successfully.

  • 404

    A VPC with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.vpc.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPCPatch

The VPC patch

  • curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id?version=2024-04-16&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

Response Body

VPC

Status Code

  • 200

    The VPC was updated successfully.

  • 400

    An invalid VPC patch was provided.

  • 404

    A VPC with the specified identifier could not be found.

  • 409

    The VPC patch object has one or more of:

    • dns.enable_hub incompatible with dns.resolution_binding_count
    • dns.enable_hub incompatible with allow_dns_resolution_binding values for endpoint gateways residing in the VPC
    • dns.resolver.type incompatible with dns.resolver.servers
    • dns.resolver.type incompatible with dns.resolver.vpc
  • 412

    The provided If-Match value does not match the current ETag value of the VPC.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.read

Request

Path Parameters

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DefaultNetworkACL

Status Code

  • 200

    The default network ACL was retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.read

Request

Path Parameters

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DefaultRoutingTable

Status Code

  • 200

    The default routing table was retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Request

Path Parameters

  • id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DefaultSecurityGroup

Status Code

  • 200

    The default security group was retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.address-prefix.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

AddressPrefixCollection

Status Code

  • 200

    The address prefixes were retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.address-prefix.create

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
AddressPrefixPrototype

The prefix prototype object

  • curl -X POST   "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes?version=2024-04-16&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

Response Body

AddressPrefix

Status Code

  • 201

    The prefix was created successfully.

  • 400

    An invalid prefix prototype object was provided.

  • 404

    The specified VPC could not be found.

  • 409

    The prefix prototype object conflicts with another prefix in the VPC.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.address-prefix.delete

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The prefix identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The address prefix was deleted successfully.

  • 404

    An address prefix with the specified identifier could not be found.

  • 409

    The address prefix is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve an address prefix

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

GET /vpcs/{vpc_id}/address_prefixes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.address-prefix.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The prefix identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

AddressPrefix

Status Code

  • 200

    The prefix was retrieved successfully.

  • 404

    A prefix with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.address-prefix.update

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The prefix identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonAddressPrefixPatch

The prefix patch

  • curl -X PATCH   "$vpc_api_endpoint/v1/vpcs/$vpc_id/address_prefixes/$address_prefix_id?version=2024-04-16&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

Response Body

AddressPrefix

Status Code

  • 200

    The prefix was updated successfully.

  • 400

    An invalid prefix patch was provided.

  • 404

    A prefix with the specified identifier could not be found.

  • 409

    The prefix patch conflicts with another prefix in the VPC.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.dns-resolution-binding.list

Auditing

Calling this method generates the following auditing event.

  • is.vpc.dns-resolution-binding.list

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • name
    string

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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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

  • account.id
    string

    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-16&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

Response Body

VPCDNSResolutionBindingCollection

Status Code

  • 200

    The DNS resolution bindings were retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.vpc.read

    Required for the VPC specified in the DNS resolution binding.

  • is.vpc.dns-resolution-binding.create

    Required 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.connect

    Required for the VPC specified in the DNS resolution binding.

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

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
VPCDNSResolutionBindingPrototype

The DNS resolution binding prototype object

  • curl -X POST   "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings?version=2024-04-16&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

Response Body

VPCDNSResolutionBinding

Status Code

  • 201

    The DNS resolution binding was created successfully.

  • 400

    An invalid DNS resolution binding prototype object was provided.

  • 409

    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.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.dns-resolution-binding.delete

    Required for the VPC specified by the identifier in the URL.

  • is.vpc.dns-resolution-binding.disconnect

    Required for the VPC specified by the identifier in the URL if dns.enable_hub is true, otherwise required for the VPC specified in the DNS resolution binding.

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 is true, otherwise generated for the VPC specified in the DNS resolution binding.

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The DNS resolution binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPCDNSResolutionBinding

Status Code

  • 202

    The DNS resolution binding deletion request was accepted.

  • 404

    A DNS resolution binding with the specified identifier could not be found.

  • 409

    The DNS resolution binding is for a VPC that has delegated DNS resolution to the VPC specified in the DNS resolution binding.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.dns-resolution-binding.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.dns-resolution-binding.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The DNS resolution binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPCDNSResolutionBinding

Status Code

  • 200

    The DNS resolution binding was retrieved successfully.

  • 404

    A DNS resolution binding with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.dns-resolution-binding.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.dns-resolution-binding.update

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The DNS resolution binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPCDNSResolutionBindingPatch

The DNS resolution binding patch

  • curl -X PATCH   "$vpc_api_endpoint/v1/vpcs/$vpc_id/dns_resolution_bindings/$dns_resolution_binding_id?version=2024-04-16&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

Response Body

VPCDNSResolutionBinding

Status Code

  • 200

    The DNS resolution binding was updated successfully.

  • 400

    An invalid DNS resolution binding patch was provided.

  • 404

    A DNS resolution binding with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • zone.name
    string

    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

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

RouteCollectionVPCContext

Status Code

  • 200

    The routes were retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

  • is.vpc.routing-table.advertise

    Required when advertise is true.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.create

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
RoutePrototype

The route prototype object

  • curl -X POST   "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes?version=2024-04-16&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

Response Body

object

Status Code

  • 201

    The route was created successfully.

  • 400

    An invalid route prototype object was provided.

  • 404

    The specified VPC could not be found.

  • 409

    The route prototype object conflicts with another route in the VPC.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.delete

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The route was deleted successfully.

  • 404

    A route with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve a VPC route

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

GET /vpcs/{vpc_id}/routes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

object

Status Code

  • 200

    The route was retrieved successfully.

  • 404

    A route with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

  • is.vpc.routing-table.advertise

    Required when advertise is specified as true, or when advertise is currently true.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.update

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonRoutePatch

The route patch

  • curl -X PATCH   "$vpc_api_endpoint/v1/vpcs/$vpc_id/routes/$route_id?version=2024-04-16&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

Response Body

object

Status Code

  • 200

    The route was updated successfully.

  • 400

    An invalid route patch was provided.

  • 404

    A route with the specified identifier could not be found.

  • 409

    The route cannot be updated while it is being deleted.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.list

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • is_default
    boolean

    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-16&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

Response Body

RoutingTableCollection

Status Code

  • 200

    The routing tables were retrieved successfully.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.create

  • is.vpc.routing-table.advertise

    Required when advertise_routes_to is specified and not empty.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.create

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
RoutingTablePrototype

The routing table prototype object

  • curl -X POST   "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables?version=2024-04-16&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

Response Body

RoutingTable

Status Code

  • 201

    The routing table was created successfully.

  • 400

    An invalid routing table prototype object was provided.

  • 404

    The specified VPC could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.delete

Request

Custom Headers

  • If-Match
    string

    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

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The routing table identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

  • 204

    The routing table was deleted successfully.

  • 403

    The routing table is not allowed to be deleted.

  • 404

    A routing table with the specified identifier could not be found.

  • 409

    The routing table is in use and cannot be deleted.

  • 412

    The provided If-Match value does not match the current ETag value of the routing table

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The routing table identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

RoutingTable

Status Code

  • 200

    The routing table was retrieved successfully.

  • 404

    A routing table with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

  • is.vpc.routing-table.advertise

    Required when advertise_routes_to is changed.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table.update

Request

Custom Headers

  • If-Match
    string

    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

  • vpc_id
    Required*
    string

    The VPC identifier

  • id
    Required*
    string

    The routing table identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonRoutingTablePatch

The routing table patch

  • curl -X PATCH   "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$vpc_routing_id?version=2024-04-16&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

Response Body

RoutingTable

Status Code

  • 200

    The routing table was updated successfully.

  • 400

    An invalid routing table patch was provided.

  • 404

    A routing table with the specified identifier could not be found.

  • 409

    The routing table cannot be updated while it is being deleted.

  • 412

    The provided If-Match value does not match the current ETag value of the routing table

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • routing_table_id
    Required*
    string

    The routing table identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

RouteCollection

Status Code

  • 200

    The VPC routes were retrieved successfully.

  • 404

    The specified VPC routing table could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

  • is.vpc.routing-table.advertise

    Required when advertise is true.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.create

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • routing_table_id
    Required*
    string

    The routing table identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
RoutePrototype

The VPC route prototype object

  • curl -X POST "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes?version=2024-04-16&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

Response Body

Route

Status Code

  • 201

    The VPC route was created successfully.

  • 400

    An invalid VPC route prototype object was provided.

  • 404

    A VPC routing table with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.delete

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • routing_table_id
    Required*
    string

    The routing table identifier

  • id
    Required*
    string

    The VPC routing table route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The VPC route was deleted successfully.

  • 403

    The VPC route is not allowed to be deleted.

  • 404

    The specified VPC route could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.read

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.read

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • routing_table_id
    Required*
    string

    The routing table identifier

  • id
    Required*
    string

    The VPC routing table route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Route

Status Code

  • 200

    The VPC route was retrieved successfully.

  • 404

    The specified VPC route could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpc.routing-table.update

  • is.vpc.routing-table.advertise

    Required when advertise is specified as true, or when advertise is currently true.

Auditing

Calling this method generates the following auditing event.

  • is.vpc.routing-table-route.update

Request

Path Parameters

  • vpc_id
    Required*
    string

    The VPC identifier

  • routing_table_id
    Required*
    string

    The routing table identifier

  • id
    Required*
    string

    The VPC routing table route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonRoutePatch

The VPC route patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/vpcs/$vpc_id/routing_tables/$routing_table_id/routes/$id?version=2024-04-16&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

Response Body

Route

Status Code

  • 200

    The VPC route was updated successfully.

  • 400

    An invalid VPC route patch was provided.

  • 403

    The VPC route is not allowed to be updated.

  • 404

    The specified VPC route could not be found.

  • 409

    The VPC route cannot be updated while it is being deleted.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.list

  • is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.subnet.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • zone.name
    string

    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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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

  • routing_table.id
    string

    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_]+$

  • routing_table.name
    string

    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-16&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

Response Body

SubnetCollection

Status Code

  • 200

    The subnets were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.create

  • is.vpc.vpc.operate

  • is.public-gateway.public-gateway.operate

    Required when public_gateway is specified

  • is.network-acl.network-acl.operate

  • is.vpc.routing-table.operate

Auditing

Calling this method generates the following auditing event.

  • is.subnet.subnet.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The subnet prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/subnets?version=2024-04-16&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

Response Body

Subnet

Status Code

  • 201

    The subnet was created successfully.

  • 400

    An invalid subnet prototype object was provided.

  • 409

    The subnet prototype object conflicts with another subnet in the VPC, or specifies a CIDR block outside of the VPC's address prefixes.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.delete

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 to true 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

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The subnet was deleted successfully.

  • 404

    A subnet with the specified identifier could not be found.

  • 409

    The subnet is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a subnet

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

GET /subnets/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.subnet.read

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Subnet

Status Code

  • 200

    The subnet was retrieved successfully.

  • 404

    A subnet with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.update

  • is.public-gateway.public-gateway.operate

    Required when public_gateway is specified

  • is.network-acl.network-acl.operate

    Required when network_acl is specified

  • is.vpc.routing-table.operate

    Required when routing_table is changed

Auditing

Calling this method generates the following auditing event.

  • is.subnet.subnet.update

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSubnetPatch

The subnet patch

  • curl -X PATCH "$vpc_api_endpoint/v1/subnets/$subnet_id?version=2024-04-16&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

Response Body

Subnet

Status Code

  • 200

    The subnet was updated successfully.

  • 400

    An invalid subnet patch was provided.

  • 404

    A subnet with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

  • is.network-acl.network-acl.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.subnet.read

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

NetworkACL

Status Code

  • 200

    The attached network ACL was retrieved successfully.

  • 404

    The specified subnet could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.operate

  • is.network-acl.network-acl.operate

Auditing

Calling this method generates the following auditing event.

  • is.subnet.network-acl.update

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
One of

The network ACL identity

  • curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/network_acl?version=2024-04-16&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

Response Body

NetworkACL

Status Code

  • 201

    The network ACL was attached successfully.

  • 400

    An invalid request body was provided.

  • 404

    A subnet with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.operate

  • is.public-gateway.public-gateway.operate

Auditing

Calling this method generates the following auditing events.

  • is.subnet.subnet.detach

  • is.public-gateway.public-gateway.detach

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The public gateway was detached successfully.

  • 404

    The specified subnet could not be found or has no public gateway.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

  • is.public-gateway.public-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.public-gateway.read

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

PublicGateway

Status Code

  • 200

    The attached public gateway was retrieved successfully.

  • 404

    The specified subnet could not be found or has no public gateway.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.operate

  • is.public-gateway.public-gateway.operate

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

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
One of

The public gateway identity

  • curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/public_gateway?version=2024-04-16&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

Response Body

PublicGateway

Status Code

  • 201

    The public gateway was attached successfully.

  • 400

    An invalid request body was provided.

  • 404

    A subnet with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

  • is.vpc.routing-table.read

    Required for the VPC with the attached routing table

Auditing

Calling this method generates the following auditing event.

  • is.subnet.routing-table.read

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

RoutingTable

Status Code

  • 200

    The attached routing table was retrieved successfully.

  • 404

    The specified subnet could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.operate

  • is.vpc.routing-table.operate

    Required for the VPC with the routing table being replaced

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 routing table

  • is.vpc.routing-table.detach

    Generated for the replaced routing table

  • is.vpc.routing-table.attach

Request

Path Parameters

  • id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
One of

The routing table identity

  • curl -X PUT "$vpc_api_endpoint/v1/subnets/$subnet_id/routing_table?version=2024-04-16&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

Response Body

RoutingTable

Status Code

  • 201

    The routing table was attached successfully.

  • 400

    An invalid request body was provided.

  • 404

    A subnet with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.subnet.reserved-ip.read

    Generated for each reserved IP in the list.

Request

Path Parameters

  • subnet_id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    Allowable values: [address,created_at,name]

    Default: address

    Example: name

  • target.id
    string

    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_]+$

  • target.crn
    string

    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

  • target.name
    string

    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

  • target.resource_type
    string

    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-16&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

Response Body

ReservedIPCollection

Status Code

  • 200

    The reserved IPs were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.update

  • is.endpoint-gateway.endpoint-gateway.operate

    Required when target specifies an endpoint gateway

  • is.virtual-network-interface.virtual-network-interface.operate

    Required when target specifies a virtual network interface

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 gateway

  • is.subnet.reserved-ip.attach

    Generated when target is specified

  • is.virtual-network-interface.virtual-network-interface.attach

    Generated when target specifies a virtual network interface

Request

Path Parameters

  • subnet_id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
ReservedIPPrototype

The reserved IP prototype object

  • curl -X POST "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips?version=2024-04-16&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

Response Body

ReservedIP

Status Code

  • 201

    The reserved IP was created successfully.

  • 400

    An invalid reserved IP prototype object was provided.

  • 409

    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.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.update

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 gateway

  • is.virtual-network-interface.virtual-network-interface.detach

    Generated when target specified a virtual network interface

Request

Path Parameters

  • subnet_id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The reserved IP was deleted successfully.

  • 403

    The specified reserved IP is owned by the provider.

  • 404

    The specified reserved IP could not be found.

  • 409

    The reserved IP is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.reserved-ip.read

Request

Path Parameters

  • subnet_id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIP

Status Code

  • 200

    The reserved IP was retrieved successfully.

  • 404

    The specified reserved IP could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.update

Auditing

Calling this method generates the following auditing event.

  • is.subnet.reserved-ip.update

Request

Path Parameters

  • subnet_id
    Required*
    string

    The subnet identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonReservedIPPatch

The reserved IP patch

  • curl -X PATCH "$vpc_api_endpoint/v1/subnets/$subnet_id/reserved_ips/$id?version=2024-04-16&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

Response Body

ReservedIP

Status Code

  • 200

    The reserved IP was updated successfully.

  • 400

    An invalid reserved IP patch was provided.

  • 403

    The specified reserved IP is owned by the provider.

  • 404

    The specified reserved IP could not be found.

  • 409

    The specified reserved IP is unbound and would be automatically deleted.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.image.image.list

  • is.image.image.read

Auditing

Calling this method generates the following auditing event.

  • is.image.image.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • status
    string[]

    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

  • visibility
    string

    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]+)*$

  • user_data_format
    string[]

    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-16&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

Response Body

ImageCollection

Status Code

  • 200

    The images were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.image.image.create

  • is.image.image.deprecate

    Required if deprecation_at is specified.

  • is.image.image.obsolete

    Required if obsolescence_at is specified.

  • is.volume.volume.operate

    Required if an image is being created from an existing volume.

  • is.instance.instance.operate

    Required if an image is being created from an existing volume that is attached to an existing instance.

Auditing

Calling this method generates the following auditing event.

  • is.image.image.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The image prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/images?version=2024-04-16&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

Response Body

Image

Status Code

  • 201

    The image was created successfully

  • 400

    An invalid image prototype object was provided.

  • 409

    The image prototype object specified a volume or encryption key that cannot be used in its current state.

Example responses
  • {
  "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 of deleting
  • has a status of pending with a status_reasons code of image_request_in_progress
  • has catalog_offering.managed set to true
DELETE /images/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.delete

Auditing

Calling this method generates the following auditing event.

  • is.image.image.delete

Request

Path Parameters

  • id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The image deletion request was accepted.

  • 403

    The image is not allowed to be deleted.

  • 404

    An image with the specified identifier could not be found.

  • 409

    The image cannot be deleted in its current state.

No Sample Response

This method does not specify any sample responses.

Retrieve an image

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

GET /images/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.read

Auditing

Calling this method generates the following auditing event.

  • is.image.image.read

Request

Path Parameters

  • id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Image

Status Code

  • 200

    The image was retrieved successfully

  • 404

    An image with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.image.image.update

    Required if name is specified.

  • is.image.image.deprecate

    Required if deprecation_at is specified.

  • is.image.image.obsolete

    Required if obsolescence_at is specified.

Auditing

Calling this method generates the following auditing event.

  • is.image.image.update

Request

Path Parameters

  • id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonImagePatch

The image patch

  • curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=2024-04-16&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

Response Body

Image

Status Code

  • 200

    The image was updated successfully

  • 400

    An invalid image patch was provided.

  • 403

    The image is not allowed to be updated.

  • 404

    An image with the specified identifier could not be found.

  • 409

    The image cannot be updated in its current state.

Example responses
  • {
  "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 of available
  • have catalog_offering.managed set to false
  • 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.deprecate

Auditing

Calling this method generates the following auditing event.

  • is.image.image-status.update

Request

Path Parameters

  • id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 204

    The image was deprecated successfully.

  • 403

    The image is not allowed to be deprecated.

  • 404

    An image with the specified identifier could not be found.

  • 409

    The image cannot be deprecated in its current state.

No Sample Response

This method does not specify any sample responses.

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 of available or deprecated
  • have catalog_offering.managed set to false
  • 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.obsolete

Auditing

Calling this method generates the following auditing event.

  • is.image.image-status.update

Request

Path Parameters

  • id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 204

    The image was obsoleted successfully.

  • 403

    The image is not allowed to be obsoleted.

  • 404

    An image with the specified identifier could not be found.

  • 409

    The image cannot be obsoleted in its current state.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.read

Auditing

Calling this method generates the following auditing event.

  • is.image.image-export-job.list

Request

Path Parameters

  • image_id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • name
    string

    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-16&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

Response Body

ImageExportJobUnpaginatedCollection

Status Code

  • 200

    The image export jobs were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.image.image.operate

  • is.image.image.export

Auditing

Calling this method generates the following auditing events.

  • is.image.image.export

  • is.image.image-export-job.create

Request

Path Parameters

  • image_id
    Required*
    string

    The image identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
ImageExportJobPrototype

The image export job prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/images/$image_id/export_jobs?version=2024-04-16&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

Response Body

ImageExportJob

Status Code

  • 201

    The image export job was created successfully.

  • 400

    An invalid image export job prototype object was provided.

  • 403

    The image is not allowed to be exported.

  • 409

    The specified image cannot be exported in its current state.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.image.image.operate

  • is.image.image.export

    Required when the image export job has not yet completed.

Auditing

Calling this method generates the following auditing event.

  • is.image.image-export-job.delete

Request

Path Parameters

  • image_id
    Required*
    string

    The image identifier

  • id
    Required*
    string

    The image export job identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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
)

Response

Status Code

  • 202

    The image export job deletion request was accepted.

  • 404

    The specified image export job could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.read

Auditing

Calling this method generates the following auditing event.

  • is.image.image-export-job.read

Request

Path Parameters

  • image_id
    Required*
    string

    The image identifier

  • id
    Required*
    string

    The image export job identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ImageExportJob

Status Code

  • 200

    The image export job was retrieved successfully.

  • 404

    The specified image export job could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.image.image.update

Auditing

Calling this method generates the following auditing event.

  • is.image.image-export-job.update

Request

Path Parameters

  • image_id
    Required*
    string

    The image identifier

  • id
    Required*
    string

    The image export job identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonImageExportJobPatch

The image export job patch

  • curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id/export_jobs/$image_export_job_id?version=2024-04-16&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

Response Body

ImageExportJob

Status Code

  • 200

    The image export job was updated successfully.

  • 400

    An invalid image export job patch was provided.

  • 404

    An image export job with the specified identifier could not be found.

Example responses
  • {
  "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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

OperatingSystemCollection

Status Code

  • 200

    The operating systems were retrieved successfully.

Example responses
  • {
  "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

  • name
    Required*
    string

    The operating system name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

OperatingSystem

Status Code

  • 200

    The operating system was retrieved successfully.

  • 404

    An operating system with the specified name could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.key.key.list

  • is.key.key.read

Auditing

Calling this method generates the following auditing event.

  • is.key.key.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

KeyCollection

Status Code

  • 200

    The keys were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.key.key.create

Auditing

Calling this method generates the following auditing event.

  • is.key.key.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
KeyPrototype

The key prototype object

  • curl -X POST "$vpc_api_endpoint/v1/keys?version=2024-04-16&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

Response Body

Key

Status Code

  • 201

    The key was created successfully.

  • 400

    An invalid key prototype object was provided.

Example responses
  • {
  "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"
}

Delete a key

This request deletes a key. This operation cannot be reversed.

DELETE /keys/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.key.key.delete

Auditing

Calling this method generates the following auditing event.

  • is.key.key.delete

Request

Path Parameters

  • id
    Required*
    string

    The key identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The key was deleted successfully.

  • 404

    A key with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve a key

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

GET /keys/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.key.key.read

Auditing

Calling this method generates the following auditing event.

  • is.key.key.read

Request

Path Parameters

  • id
    Required*
    string

    The key identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Key

Status Code

  • 200

    The key was retrieved successfully.

  • 404

    A key with the specified identifier could not be found.

Example responses
  • {
  "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"
}

Update a key

This request updates a key's name.

PATCH /keys/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.key.key.update

Auditing

Calling this method generates the following auditing event.

  • is.key.key.update

Request

Path Parameters

  • id
    Required*
    string

    The key identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonKeyPatch

The key patch

  • curl -X PATCH "$vpc_api_endpoint/v1/keys/$id?version=2024-04-16&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

Response Body

Key

Status Code

  • 200

    The key was updated successfully.

  • 400

    An invalid key patch was provided.

  • 404

    A key with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceProfileCollection

Status Code

  • 200

    The instance profiles were retrieved successfully

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Request

Path Parameters

  • name
    Required*
    string

    The instance profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceProfile

Status Code

  • 200

    The instance profile was retrieved successfully

  • 404

    An instance profile with the specified name could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.template.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-template.instance-template.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceTemplateCollection

Status Code

  • 200

    The instance templates were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.template.create

Auditing

Calling this method generates the following auditing event.

  • is.instance-template.instance-template.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The instance template prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/instance/templates?version=2024-04-16&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

Response Body

Status Code

  • 201

    The instance template was created successfully.

  • 400

    An invalid instance template prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.template.delete

Auditing

Calling this method generates the following auditing event.

  • is.instance-template.instance-template.delete

Request

Path Parameters

  • id
    Required*
    string

    The instance template identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance template was deleted successfully.

  • 404

    An instance template could not be found.

  • 409

    The instance template is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve an instance template

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

GET /instance/templates/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.template.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-template.instance-template.read

Request

Path Parameters

  • id
    Required*
    string

    The instance template identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The instance template was retrieved successfully.

  • 404

    An instance template with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.template.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-template.instance-template.update

Request

Path Parameters

  • id
    Required*
    string

    The instance template identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceTemplatePatch

The instance template patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance/templates/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The instance template was updated successfully.

  • 400

    An invalid instance template patch was provided.

  • 404

    An instance template with the specified identifier could not be found.

Example responses
  • {
  "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"
  }
}

List all instances

This request lists all instances in the region.

GET /instances

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance.instance.list

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.instance.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • dedicated_host.id
    string

    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_]+$

  • dedicated_host.crn
    string

    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

  • dedicated_host.name
    string

    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

  • placement_group.id
    string

    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_]+$

  • placement_group.crn
    string

    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

  • placement_group.name
    string

    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

  • reservation.id
    string

    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_]+$

  • reservation.crn
    string

    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

  • reservation.name
    string

    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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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-16&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

Response Body

InstanceCollection

Status Code

  • 200

    The instances were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.create

  • is.instance.instance.ip-spoofing

    Required when allow_ip_spoofing is true on any instance network interface

  • is.subnet.subnet.operate

    Required for each subnet with an existing reserved IP being attached to an instance network interface or to a virtual network interface

  • is.subnet.subnet.update

  • is.reservation.reservation.operate

    Required when reservation_affinity.pools is specified.

  • is.volume.volume.create

    Required when image is specified, or boot_volume_attachment or volume_attachments specifies a new volume

  • is.volume.volume.operate

    Required when boot_volume_attachment or volume_attachments specifies an existing volume

  • is.security-group.security-group.operate

    Required for instance network interfaces, or for instance network attachments that specify a new virtual network interface

  • is.vpc.vpc.operate

  • is.key.key.operate

    Required when keys is specified

  • is.image.image.operate

    Required when image is specified

  • is.dedicated-host.dedicated-host-group.operate

    Required when placement_target specifies a dedicated host group

  • is.dedicated-host.dedicated-host.operate

    Required when placement_target specifies a dedicated host

  • is.snapshot.snapshot.operate

    Required when boot_volume_attachment or volume_attachments specifies a snapshot to create a new volume from.

  • is.placement-group.placement-group.operate

    Required when placement_target specifies a placement group

  • globalcatalog-collection.instance.retrieve

    Required when catalog_offering is specified

  • iam-identity.profile.get

    Required when default_trusted_profile.target specifies a trusted profile

  • iam-identity.profile.update

    Required when default_trusted_profile.auto_link is true

  • iam-identity.profile.linkToResource

    Required when default_trusted_profile.auto_link is true

  • is.virtual-network-interface.virtual-network-interface.create

    Required for instance network attachments that specify a new virtual network interface

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required for instance network attachments that specify a new virtual network interface with enable_infrastructure_nat set to false

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required for instance network attachments that specify a new virtual network interface with allow_ip_spoofing set to true

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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The instance prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/instances?version=2024-04-16&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

Response Body

Instance

Status Code

  • 201

    The instance was created successfully.

  • 400

    An invalid instance prototype object was provided.

  • 409

    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
Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.delete

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 to true

  • is.subnet.reserved-ip.delete

    Generated for each reserved IP that had auto_delete set to true that was attached to:

    • a network interface on the instance, or
    • a virtual network interface that had auto_delete set to true

  • 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 to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true

  • is.virtual-network-interface.virtual-network-interface.detach

    Generated for:

    • each attached virtual network interface
    • each virtual network interface that had auto_delete set to true, for each attached reserved IP

  • is.virtual-network-interface.virtual-network-interface.delete

    Generated for each virtual network interface that had auto_delete set to true

  • 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 to true

  • is.flow-log-collector.flow-log-collector.delete

    Generated for each flow log collector that had auto_delete set to true 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 to true

  • 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 to true

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance was deleted successfully.

  • 403

    The instance is not allowed to be deleted.

  • 404

    An instance with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the instance

No Sample Response

This method does not specify any sample responses.

Retrieve an instance

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

GET /instances/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.instance.read

Request

Path Parameters

  • id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Instance

Status Code

  • 200

    The instance was retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

  • is.reservation.reservation.operate

    Required when reservation_affinity.pools is specified.

  • is.dedicated-host.dedicated-host-group.operate

    Required when placement_target specifies a dedicated host group, or the placement target being replaced is a dedicated host group.

  • is.dedicated-host.dedicated-host.operate

    Required when placement_target specifies a dedicated host, or the placement target being replaced is a dedicated host.

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-Match
    string

    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

  • id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstancePatch

The instance patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-04-16&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

Response Body

Instance

Status Code

  • 200

    The instance was updated successfully.

  • 400

    An invalid instance patch was provided.

  • 403

    The instance is not allowed to be updated.

  • 404

    An instance with the specified identifier could not be found.

  • 409

    The provided instance patch object specified one or more of:

    • A property that can only be changed while the instance status is stopped or stopping
    • An instance profile does not support the instance configuration
    • A placement target or reservation attachment policy that conflict with each other
  • 412

    The provided If-Match value does not match the current ETag value of the instance

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Request

Path Parameters

  • id
    Required*
    string

    The instance identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceInitialization

Status Code

  • 200

    The initialization configuration was retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.operate

Auditing

Calling this method generates the following auditing event.

  • is.instance.action.create

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
InstanceActionPrototype

The instance action prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/actions?version=2024-04-16&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

Response Body

InstanceAction

Status Code

  • 201

    The action was created successfully and will run in the order it was received.

  • 400

    The specified action could not be created.

  • 403

    The action is not allowed to be created.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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

Auditing

Calling this method generates the following auditing event.

  • is.instance.console.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • access_token
    string

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

    Example: VGhpcyBJcyBhIHRva2Vu

Response

Status Code

  • 101

    A WebSocket connection was established.

  • 400

    The open console limit for virtual server instances was reached.

  • 401

    An invalid instance console access token was provided.

  • 404

    An instance with the specified identifier could not be found.

  • 426

    The WebSocket protocol is required.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance.instance.operate

  • is.instance.instance.console

Auditing

Calling this method generates the following auditing event.

  • is.instance.console-access-token.create

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
InstanceConsoleAccessTokenPrototype

The instance console access token prototype

  • curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/console_access_token?version=2024-04-16&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

Response Body

InstanceConsoleAccessToken

The instance console access token information

Status Code

  • 200

    The access token was created successfully.

  • 400

    An invalid instance console access token prototype object was provided.

  • 403

    The access token is not allowed to be created.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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-16&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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.disk.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Response Body

InstanceDiskCollection

Status Code

  • 200

    The instance disks were retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve an instance disk

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

GET /instances/{instance_id}/disks/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.disk.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceDisk

Status Code

  • 200

    The instance disk was retrieved successfully.

  • 404

    An instance disk with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Update an instance disk

This request updates the instance disk with the information in a provided patch.

PATCH /instances/{instance_id}/disks/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

Auditing

Calling this method generates the following auditing event.

  • is.instance.disk.update

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceDiskPatch

The instance disk patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/disks/$disk_id?version=2024-04-16&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

Response Body

InstanceDisk

Status Code

  • 200

    The instance disk was updated successfully.

  • 400

    An invalid instance disk patch was provided.

  • 403

    The instance disk is not allowed to be updated.

  • 404

    An instance disk with the specified identifier could not be found for the specified instance.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-attachment.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceNetworkAttachmentCollection

Status Code

  • 200

    The instance network attachments were retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

  • is.security-group.security-group.operate

    Required for instance network attachments that specify a new virtual network interface

  • is.subnet.subnet.operate

    Required for instance network attachments that specify a new virtual network interface and an existing reserved IP on a subnet

  • is.subnet.subnet.update

    Required for instance network attachments that specify a new virtual network interface and a new reserved IP on a subnet

  • is.virtual-network-interface.virtual-network-interface.create

    Required for instance network attachments that specify a new virtual network interface

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required for instance network attachments that specify a new virtual network interface with enable_infrastructure_nat set to false

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required for instance network attachments that specify a new virtual network interface with allow_ip_spoofing set to true

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

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
InstanceNetworkAttachmentPrototype

The instance network attachment prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments?version=2024-04-16&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

Response Body

InstanceNetworkAttachment

Status Code

  • 201

    The instance network attachment was created successfully.

  • 400

    An invalid instance network attachment prototype object was provided.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

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 to true

  • is.virtual-network-interface.virtual-network-interface.delete

    Generated when the virtual network interface had auto_delete set to true

  • is.floating-ip.floating-ip.detach

    Generated for each floating IP that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.reserved-ip.detach

    Generated for each reserved IP that was attached to an virtual network interface that had auto_delete set to true

  • is.subnet.reserved-ip.delete

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.security-group.security-group.detach

    Generated for each security group that was attached to a virtual network interface that had auto_delete set to true

  • is.flow-log-collector.flow-log-collector.delete

    Generated for each flow log collector that had auto_delete set to true that was attached to:

    • this instance network attachment
    • a virtual network interface that had auto_delete set to true

  • 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 to true

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 202

    The instance network attachment deletion request was accepted.

  • 403

    The instance network attachment is not allowed to be deleted.

  • 404

    A instance network attachment with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-attachment.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceNetworkAttachment

Status Code

  • 200

    The instance network attachment was retrieved successfully.

  • 404

    A instance network attachment with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-attachment.update

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceNetworkAttachmentPatch

The instance network attachment patch

Examples:
View
  • curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/network_attachments/$network_attachment_id?version=2024-04-16&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

Response Body

InstanceNetworkAttachment

Status Code

  • 200

    The instance network attachment was updated successfully.

  • 400

    An invalid instance network attachment patch was provided.

  • 404

    A instance network attachment with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-interface.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

NetworkInterfaceUnpaginatedCollection

Status Code

  • 200

    The instance network interfaces were retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

  • is.instance.instance.ip-spoofing

    Required when allow_ip_spoofing is true

  • is.security-group.security-group.operate

  • is.subnet.subnet.operate

    Required for instance network interfaces that specify an existing reserved IP on a subnet

  • is.subnet.subnet.update

    Required for instance network interfaces that specify a new reserved IP on a subnet

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

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
NetworkInterfacePrototype

The instance network interface prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces?version=2024-04-16&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

Response Body

NetworkInterface

Status Code

  • 201

    The instance network interface was created successfully.

  • 400

    An invalid instance network interface prototype object was provided.

  • 403

    The instance network interface is not allowed to be created.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

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 to true that was attached to this instance network interface

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true that was attached to this instance network interface

  • is.flow-log-collector.flow-log-collector.delete

    Generated for each flow log collector that had auto_delete set to true that was attached to this instance network interface

  • is.flow-log-collector.flow-log-collector.detach

    Generated for each flow log collector that was attached to this instance network interface

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance network interface was deleted successfully.

  • 403

    The instance network interface is not allowed to be deleted.

  • 404

    An instance network interface with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-interface.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

NetworkInterface

Status Code

  • 200

    The instance network interface was retrieved successfully.

  • 404

    An instance network interface with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

  • is.instance.instance.ip-spoofing

    Required when allow_ip_spoofing is true

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-interface.update

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonNetworkInterfacePatch

The instance network interface patch

Examples:
View
  • curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/network_interfaces/$network_interface_id?version=2024-04-16&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

Response Body

NetworkInterface

Status Code

  • 200

    The instance network interface was updated successfully.

  • 400

    An invalid instance network interface patch was provided.

  • 403

    The instance network interface is not allowed to be updated.

  • 404

    An instance network interface with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

  • is.floating-ip.floating-ip.read

    Required for all floating IPs associated with the instance network interface

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-interface_floating-ip.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIPUnpaginatedCollection

Status Code

  • 200

    The associated floating IPs were retrieved successfully.

  • 404

    An instance network interface with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance.instance.operate

  • is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing events.

  • is.instance.network-interface.detach

  • is.floating-ip.floating-ip.detach

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The floating IP was disassociated successfully.

  • 403

    The floating IP is not allowed to be disassociated.

  • 404

    The specified floating IP address is not associated with the instance network interface with the specified identifier

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

  • is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.network-interface_floating-ip.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIP

Status Code

  • 200

    The associated floating IP was retrieved successfully.

  • 404

    The floating IP address is not associated with an instance network interface with the specified identifier

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.operate

    Required for the instance associated with the specified instance network interface, and for the instance associated with the instance network interface being replaced (if any).

  • is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing events.

  • is.instance.network-interface.attach

  • is.floating-ip.floating-ip.attach

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIP

Status Code

  • 201

    The floating IP was successfully associated with the instance network interface.

  • 400

    The specified floating IP could not be associated with the specified instance network interface.

  • 403

    The floating IP is not allowed to be associated.

  • 404

    The specified instance network interface or floating IP could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

  • is.subnet.subnet.read

    Required for the subnet attached to the instance network interface

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.subnet.reserved-ip.read

    Generated for each reserved IP in the list.

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

ReservedIPCollectionInstanceNetworkInterfaceContext

Status Code

  • 200

    The reserved IPs were retrieved successfully.

  • 404

    An instance network interface with the specified identifier could not be found for the specified instance.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

  • is.subnet.subnet.read

    Required for the subnet attached to the instance network interface

Auditing

Calling this method generates the following auditing event.

  • is.subnet.reserved-ip.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The instance network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIP

Status Code

  • 200

    The bound reserved IP was retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.volume-attachment.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VolumeAttachmentCollection

Status Code

  • 200

    The volume attachments were retrieved successfully.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

  • is.volume.volume.operate

    Required when volume specifies an existing volume

  • is.volume.volume.create

    Required when volume specifies a new volume

  • is.snapshot.snapshot.operate

    Required when volume specifies a snapshot to create a new volume from

Auditing

Calling this method generates the following auditing event.

  • is.instance.volume-attachment.create

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
VolumeAttachmentPrototype

The volume attachment prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments?version=2024-04-16&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

Response Body

VolumeAttachment

Status Code

  • 201

    The volume attachment was created successfully, attaching the specified volume to the instance.

  • 400

    An invalid volume attachment prototype object was provided.

  • 403

    The volume attachment is not allowed to be created.

  • 404

    An instance with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance.instance.operate

  • is.volume.volume.operate

Auditing

Calling this method generates the following auditing event.

  • is.instance.volume-attachment.delete

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The volume attachment identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

  • 204

    The volume attachment was deleted successfully, detaching its volume from the instance.

  • 400

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

  • 403

    The volume attachment is not allowed to be deleted.

  • 404

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.read

Auditing

Calling this method generates the following auditing event.

  • is.instance.volume-attachment.read

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The volume attachment identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VolumeAttachment

Status Code

  • 200

    The volume attachment was retrieved successfully.

  • 404

    A volume attachment with the specified identifier could not be found for the specified instance.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance.instance.update

Auditing

Calling this method generates the following auditing event.

  • is.instance.volume-attachment.update

Request

Path Parameters

  • instance_id
    Required*
    string

    The virtual server instance identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The volume attachment identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVolumeAttachmentPatch

The volume attachment patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id/volume_attachments/$volume_attachment_id?version=2024-04-16&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

Response Body

VolumeAttachment

Status Code

  • 200

    The volume attachment was updated successfully.

  • 400

    An invalid volume attachment patch was provided.

  • 403

    The volume attachment is not allowed to be updated.

  • 404

    A volume attachment with the specified identifier could not be found for the specified instance.

Example responses
  • {
  "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"
  }
}

List all instance groups

This request lists all instance groups in the region.

GET /instance_groups

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.list

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

InstanceGroupCollection

Status Code

  • 200

    The instance groups were retrieved successfully.

Example responses
  • {
  "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
}

Create an instance group

This request creates a new instance group

POST /instance_groups

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.create

  • is.instance.instance-template.read

  • is.subnet.subnet.operate

  • is.load-balancer.load-balancer.manage

    Required when load_balancer and/or load_balancer_pool is specified

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
InstanceGroupPrototype

The instance group prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instance_groups?version=2024-04-16&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

Response Body

InstanceGroup

Status Code

  • 201

    The instance group was created successfully.

  • 400

    An invalid instance group prototype object was provided.

  • 409

    The instance group prototype object specified in a load balancer pool that is already in use by another instance group in the VPC.

Example responses
  • {
  "$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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.delete

  • is.instance.instance.delete

  • is.load-balancer.load-balancer.manage

    Required when the instance group manages a load balancer

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.delete

Request

Path Parameters

  • id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group was deleted successfully.

  • 403

    The instance group is not allowed to be deleted.

  • 404

    An instance group with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve an instance group

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

GET /instance_groups/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.read

Request

Path Parameters

  • id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceGroup

Status Code

  • 200

    The instance group was retrieved successfully.

  • 404

    An instance group with the specified identifier could not be found.

Example responses
  • {
  "$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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

  • is.instance.instance-template.read

    Required when instance_template is specified

  • is.subnet.subnet.operate

    Required when subnets is specified

  • is.load-balancer.load-balancer.manage

    Required when load_balancer_pool is specified

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.update

Request

Path Parameters

  • id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceGroupPatch

The instance group patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$id?version=2024-04-16&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

Response Body

InstanceGroup

Status Code

  • 200

    The instance group was updated successfully.

  • 400

    An invalid instance group patch was provided.

  • 403

    The instance group is not allowed to be updated.

  • 404

    An instance group with the specified identifier could not be found.

  • 409

    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.

Example responses
  • {
  "$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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.load-balancer.delete

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group load balancer was deleted successfully.

  • 403

    The instance group load balancer is not allowed to be deleted.

  • 404

    An instance group load balancer could not be found.

No Sample Response

This method does not specify any sample responses.

List all managers for an instance group

This request lists all managers for an instance group.

GET /instance_groups/{instance_group_id}/managers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

InstanceGroupManagerCollection

Status Code

  • 200

    The instance group managers were retrieved successfully.

  • 404

    An instance group with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager.create

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The instance group manager prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers?version=2024-04-16&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

Response Body

Status Code

  • 201

    The instance group manager was created successfully.

  • 400

    An invalid instance group manager prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager.delete

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group manager was deleted successfully.

  • 403

    The instance group manager is not allowed to be deleted.

  • 404

    An instance group manager with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The instance group manager was retrieved successfully.

  • 404

    An instance group manager with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceGroupManagerPatch

The instance group manager patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The instance group manager was updated successfully.

  • 400

    An invalid instance group manager patch was provided.

  • 403

    The instance group manager is not allowed to be updated.

  • 404

    An instance group manager with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.list

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_action.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

InstanceGroupManagerActionsCollection

Status Code

  • 200

    The instance group manager actions were retrieved successfully.

  • 404

    An instance group manager with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_action.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The instance group manager action prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions?version=2024-04-16&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

Response Body

Status Code

  • 201

    The instance group manager action was created successfully.

  • 400

    An invalid instance group manager action prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_action.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager action identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group manager action was deleted successfully.

  • 403

    The instance group manager action is not allowed to be deleted.

  • 404

    An instance group manager action with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.instance-group.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager action identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The instance group manager action was retrieved successfully.

  • 404

    An instance group manager action with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_action.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager action identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceGroupManagerActionPatch

The instance group manager action patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/actions/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The instance group manager action was updated successfully.

  • 400

    An invalid instance group manager action patch was provided.

  • 403

    The instance group manager action is not allowed to be updated.

  • 404

    An instance group manager action with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_policy.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

InstanceGroupManagerPolicyCollection

Status Code

  • 200

    The instance group manager policies were retrieved successfully.

  • 404

    An instance group manager with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_policy.create

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The instance group manager policy prototype object

  • curl -X POST "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies?version=2024-04-16&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

Response Body

Status Code

  • 201

    The instance group manager policy was created successfully.

  • 400

    An invalid instance group manager policy prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_policy.delete

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group manager policy was deleted successfully.

  • 403

    The instance group manager policy is not allowed to be deleted.

  • 404

    An instance group manager policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_policy.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The instance group manager policy was retrieved successfully.

  • 404

    An instance group manager policy with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.manager_policy.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • instance_group_manager_id
    Required*
    string

    The instance group manager identifier

  • id
    Required*
    string

    The instance group manager policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceGroupManagerPolicyPatch

The instance group manager policy patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/managers/$instance_group_manager_id/policies/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The instance group manager policy was updated successfully.

  • 400

    An invalid instance group manager policy patch was provided.

  • 403

    The instance group manager policy is not allowed to be updated.

  • 404

    An instance group manager policy with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.membership.delete

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group memberships were deleted successfully.

  • 403

    The instance group memberships are not allowed to be deleted.

  • 404

    An instance group with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.membership.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

InstanceGroupMembershipCollection

Status Code

  • 200

    The instance group memberships were retrieved successfully.

  • 404

    An instance group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

    Required when delete_membership_on_instance_delete is true

  • is.instance.instance.delete

  • is.load-balancer.load-balancer.manage

    Required when the instance group manages a load balancer

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.membership.delete

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group membership identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The instance group membership was deleted successfully.

  • 403

    The instance group membership is not allowed to be deleted.

  • 404

    An instance group membership with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.read

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.membership.read

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group membership identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

InstanceGroupMembership

Status Code

  • 200

    The instance group membership was retrieved successfully.

  • 404

    An instance group membership with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.instance-group.instance-group.update

Auditing

Calling this method generates the following auditing event.

  • is.instance-group.membership.update

Request

Path Parameters

  • instance_group_id
    Required*
    string

    The instance group identifier

  • id
    Required*
    string

    The instance group membership identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonInstanceGroupMembershipPatch

The instance group membership patch

  • curl -X PATCH "$vpc_api_endpoint/v1/instance_groups/$instance_group_id/memberships/$id?version=2024-04-16&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

Response Body

InstanceGroupMembership

Status Code

  • 200

    The instance group membership was updated successfully.

  • 400

    An invalid instance group membership patch was provided.

  • 403

    The instance group membership is not allowed to be updated.

  • 404

    An instance group membership with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.list

  • is.reservation.reservation.read

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • name
    string

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

  • resource_group.id
    string

    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_]+$

  • zone.name
    string

    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-16&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

Response Body

ReservationCollection

Status Code

  • 200

    The reservations were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.create

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
ReservationPrototype

The reservation prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/reservations?version=2024-04-16&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

Response Body

Reservation

Status Code

  • 201

    The reservation was created successfully.

  • 400

    An invalid reservation prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.delete

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.delete

Request

Path Parameters

  • id
    Required*
    string

    The reservation identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Reservation

Status Code

  • 202

    The reservation deletion request was accepted.

  • 403

    The reservation is not allowed to be deleted.

  • 404

    A reservation with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.read

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.read

Request

Path Parameters

  • id
    Required*
    string

    The reservation identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Reservation

Status Code

  • 200

    The reservation was retrieved successfully.

  • 404

    A reservation with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.update

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.update

Request

Path Parameters

  • id
    Required*
    string

    The reservation identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonReservationPatch

The reservation patch

Examples:
View
  • curl -X PATCH "$vpc_api_endpoint/v1/reservations/$id?version=2024-04-16&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

Response Body

Reservation

Status Code

  • 200

    The reservation was updated successfully.

  • 400

    An invalid reservation patch was provided.

  • 404

    A reservation with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.reservation.reservation.activate

Auditing

Calling this method generates the following auditing event.

  • is.reservation.reservation.activate

Request

Path Parameters

  • id
    Required*
    string

    The reservation identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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()

Response

Status Code

  • 202

    The reservation activation request was accepted.

  • 404

    A reservation with the specified identifier could not be found.

  • 409

    The reservation cannot be activated in its current state.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host-group.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host-group.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • zone.name
    string

    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

  • name
    string

    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-16&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

Response Body

DedicatedHostGroupCollection

Status Code

  • 200

    The dedicated host groups were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host-group.create

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host-group.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
DedicatedHostGroupPrototype

The dedicated host group prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/dedicated_host/groups?version=2024-04-16&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

Response Body

DedicatedHostGroup

Status Code

  • 201

    The dedicated host group was created successfully.

  • 400

    An invalid dedicated host group prototype object was provided

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host-group.delete

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host-group.delete

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The dedicated host group was deleted successfully.

  • 404

    A dedicated host group with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host-group.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host-group.read

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DedicatedHostGroup

Status Code

  • 200

    The dedicated host group was retrieved successfully.

  • 404

    A dedicated host group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host-group.update

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host-group.update

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonDedicatedHostGroupPatch

The dedicated host group patch

Examples:
View
  • curl -X PATCH "$vpc_api_endpoint/v1/dedicated_host/groups/$dedicated_host_group_id?version=2024-04-16&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

Response Body

DedicatedHostGroup

Status Code

  • 200

    The dedicated host group was updated successfully.

  • 400

    An invalid dedicated host group patch was provided.

  • 404

    A dedicated host group with the specified identifier could not be found.

  • 409

    The dedicated host group must be empty to change family

Example responses
  • {
  "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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

DedicatedHostProfileCollection

Status Code

  • 200

    The dedicated host profiles were retrieved successfully

Example responses
  • {
  "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

  • name
    Required*
    string

    The dedicated host profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DedicatedHostProfile

Status Code

  • 200

    The dedicated host profile was retrieved successfully

  • 404

    A dedicated host profile with the specified name could not be found.

Example responses
  • {
  "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"
  }
}

List all dedicated hosts

This request lists all dedicated hosts in the region.

GET /dedicated_hosts

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • dedicated_host_group.id
    string

    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_]+$

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • zone.name
    string

    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

  • name
    string

    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-16&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

Response Body

DedicatedHostCollection

Status Code

  • 200

    The dedicated hosts were retrieved successfully.

Example responses
  • {
  "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
}

Create a dedicated host

This request creates a new dedicated host.

POST /dedicated_hosts

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.create

  • is.dedicated-host.dedicated-host-group.create

  • is.dedicated-host.dedicated-host-group.update

Auditing

Calling this method generates the following auditing events.

  • is.dedicated-host.dedicated-host.create

  • is.dedicated-host.dedicated-host-group.create

  • is.dedicated-host.dedicated-host-group.update

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The dedicated host prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/dedicated_hosts?version=2024-04-16&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

Response Body

DedicatedHost

Status Code

  • 201

    The dedicated host was created successfully.

  • 400

    An invalid dedicated host prototype object was provided

  • 409

    The dedicated host group family must match the specified host profile family

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.read

Request

Path Parameters

  • dedicated_host_id
    Required*
    string

    The dedicated host identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DedicatedHostDiskCollection

Status Code

  • 200

    The dedicated host disks were retrieved successfully.

  • 404

    A dedicated host with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.read

Request

Path Parameters

  • dedicated_host_id
    Required*
    string

    The dedicated host identifier

  • id
    Required*
    string

    The dedicated host disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DedicatedHostDisk

Status Code

  • 200

    The dedicated host disk was retrieved successfully.

  • 404

    A dedicated host disk with the specified identifier could not be found for the specified dedicated host.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.update

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.update

Request

Path Parameters

  • dedicated_host_id
    Required*
    string

    The dedicated host identifier

  • id
    Required*
    string

    The dedicated host disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonDedicatedHostDiskPatch

The dedicated host disk patch

  • curl -X PATCH "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id/disks/$disk_id?version=2024-04-16&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

Response Body

DedicatedHostDisk

Status Code

  • 200

    The dedicated host disk was updated successfully.

  • 400

    An invalid dedicated host disk patch was provided.

  • 404

    A dedicated host disk with the specified identifier could not be found for the specified dedicated host.

Example responses
  • {
  "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"
  ]
}

Delete a dedicated host

This request deletes a dedicated host.

DELETE /dedicated_hosts/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.delete

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.delete

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The dedicated host was deleted successfully.

  • 404

    A dedicated host with the specified dedicated host group and dedicated host identifiers could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve a dedicated host

This request retrieves a single dedicated host specified by the identifiers in the URL.

GET /dedicated_hosts/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.read

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.read

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

DedicatedHost

Status Code

  • 200

    The dedicated host was retrieved successfully.

  • 404

    A dedicated host with the specified dedicated host and group identifiers could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.dedicated-host.dedicated-host.update

Auditing

Calling this method generates the following auditing event.

  • is.dedicated-host.dedicated-host.update

Request

Path Parameters

  • id
    Required*
    string

    The dedicated host identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonDedicatedHostPatch

The dedicated host patch

  • curl -X PATCH "$vpc_api_endpoint/v1/dedicated_hosts/$dedicated_host_id?version=2024-04-16&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

Response Body

DedicatedHost

Status Code

  • 200

    The dedicated host was updated successfully.

  • 400

    An invalid dedicated host patch was provided.

  • 404

    A dedicated host with the specified dedicated host group and dedicated host identifiers could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.placement-group.placement-group.list

  • is.placement-group.placement-group.read

Auditing

Calling this method generates the following auditing event.

  • is.placement-group.placement-group.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

PlacementGroupCollection

Status Code

  • 200

    The placement groups were retrieved successfully.

Example responses
  • {
  "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
}

Create a placement group

This request creates a new placement group

POST /placement_groups

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.placement-group.placement-group.create

Auditing

Calling this method generates the following auditing event.

  • is.placement-group.placement-group.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
PlacementGroupPrototype

The placement group prototype object

  • curl -X POST "$vpc_api_endpoint/v1/placement_groups?version=2024-04-16&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

Response Body

PlacementGroup

Status Code

  • 201

    The placement group was created successfully.

  • 400

    An invalid placement group prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.placement-group.placement-group.delete

Auditing

Calling this method generates the following auditing event.

  • is.placement-group.placement-group.delete

Request

Path Parameters

  • id
    Required*
    string

    The placement group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The placement group deletion request was accepted.

  • 404

    A placement group with the specified identifier could not be found.

  • 409

    The placement group is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a placement group

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

GET /placement_groups/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.placement-group.placement-group.read

Auditing

Calling this method generates the following auditing event.

  • is.placement-group.placement-group.read

Request

Path Parameters

  • id
    Required*
    string

    The placement group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

PlacementGroup

Status Code

  • 200

    The placement group was retrieved successfully.

  • 404

    A placement group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.placement-group.placement-group.update

Auditing

Calling this method generates the following auditing event.

  • is.placement-group.placement-group.update

Request

Path Parameters

  • id
    Required*
    string

    The placement group identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonPlacementGroupPatch

The placement group patch

  • curl -X PATCH "$vpc_api_endpoint/v1/placement_groups/$id?version=2024-04-16&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

Response Body

PlacementGroup

Status Code

  • 200

    The placement group was updated successfully.

  • 400

    An invalid placement group patch was provided.

  • 404

    A placement group with the specified identifier could not be found.

Example responses
  • {
  "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

Auditing

Calling this method generates the following auditing event.

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

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

BareMetalServerProfileCollection

Status Code

  • 200

    The bare metal server profiles were retrieved successfully

Example responses
  • {
  "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}

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • name
    Required*
    string

    The bare metal server profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BareMetalServerProfile

Status Code

  • 200

    The bare metal server profile was retrieved successfully

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

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

Auditing

Calling this method generates the following auditing event.

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

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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-16&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

Response Body

BareMetalServerCollection

Status Code

  • 200

    The bare metal servers were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.subnet.subnet.operate

    Required for each subnet with an existing reserved IP being attached to a bare metal server network interface or to a virtual network interface

  • is.subnet.subnet.update

    Required for each subnet where a new reserved IP is specified on a bare metal server network interface or on a virtual network interface

  • is.security-group.security-group.operate

    Required for bare metal server network interfaces, or for bare metal server network attachments that specify a new virtual network interface

  • is.vpc.vpc.operate

  • is.key.key.operate

  • is.image.image.operate

  • is.bare-metal-server.bare-metal-server.ip-spoofing

    Required when allow_ip_spoofing is true on any bare metal server network interface

  • is.bare-metal-server.bare-metal-server.infrastructure-nat

    Required when enable_infrastructure_nat is false on any bare metal server network interface

  • is.virtual-network-interface.virtual-network-interface.create

    Required for bare metal server network attachments that specify a new virtual network interface

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required for bare metal server network attachments that specify a new virtual network interface with enable_infrastructure_nat set to false

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required for bare metal server network attachments that specify a new virtual network interface with allow_ip_spoofing set to true

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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The bare metal server prototype object

  • curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers?version=2024-04-16&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

Response Body

BareMetalServer

Status Code

  • 201

    The bare metal server was created successfully.

  • 400

    An invalid bare metal server prototype object was provided.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • access_token
    string

    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-16&generation=2&maturity=beta&access_token=VGhpcyBJcyBhIHRva2Vu"
  • const params = {
  bareMetalServerId: bareMetalServerId,
  accessToken: 'VGhpcyBJcyBhIHRva2Vu',
};
const response = await vpcService.getBareMetalServerConsole(params)

Response

Status Code

  • 101

    A WebSocket connection was established.

  • 400

    The open console limit for bare metal servers was reached.

  • 401

    An invalid bare metal server console access token was provided.

  • 404

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

  • 426

    The WebSocket protocol is required.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
BareMetalServerConsoleAccessTokenPrototype

The bare metal server console access token prototype

  • curl -X GET "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/console_access_token?version=2024-04-16&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

Response Body

BareMetalServerConsoleAccessToken

The bare metal server console access token information

Status Code

  • 200

    The access token was created successfully.

  • 400

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

  • 403

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

  • 404

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

Example responses
  • {
  "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-16&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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BareMetalServerDiskCollection

Status Code

  • 200

    The disks were retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BareMetalServerDisk

Status Code

  • 200

    The disk was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server disk identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBareMetalServerDiskPatch

The bare metal server disk patch

  • curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/disks/$disk_id?version=2024-04-16&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

Response Body

BareMetalServerDisk

Status Code

  • 200

    The bare metal server disk was updated successfully.

  • 400

    An invalid bare metal server disk patch was provided.

  • 403

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

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

BareMetalServerNetworkAttachmentCollection

Status Code

  • 200

    The bare metal server network attachments were retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.security-group.security-group.operate

    Required for bare metal server network attachments that specify a new virtual network interface

  • is.subnet.subnet.operate

    Required for bare metal server network attachments that specify a new virtual network interface and an existing reserved IP on a subnet

  • is.subnet.subnet.update

    Required for bare metal server network attachments that specify a new virtual network interface and a new reserved IP on a subnet

  • is.virtual-network-interface.virtual-network-interface.create

    Required for bare metal server network attachments that specify a new virtual network interface

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required for bare metal server network attachments that specify a new virtual network interface with enable_infrastructure_nat set to false

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required for bare metal server network attachments that specify a new virtual network interface with allow_ip_spoofing set to true

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

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The bare metal server network attachment prototype object

  • curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments?version=2024-04-16&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

Response Body

Status Code

  • 201

    The bare metal server network attachment was created successfully.

  • 400

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

  • 404

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

Example responses
  • {
  "$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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

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 to true

  • is.virtual-network-interface.virtual-network-interface.delete

    Generated when the virtual network interface had auto_delete set to true

  • is.floating-ip.floating-ip.detach

    Generated for each floating IP that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.reserved-ip.detach

    Generated for each reserved IP that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.reserved-ip.delete

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.security-group.security-group.detach

    Generated for each security group that was attached to a virtual network interface that had auto_delete set to true

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 202

    The bare metal server network attachment deletion request was accepted.

  • 403

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

  • 404

    A bare metal server network attachment with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The bare metal server network attachment was retrieved successfully.

  • 404

    A bare metal server network attachment with the specified identifier could not be found.

Example responses
  • {
  "$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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network attachment identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBareMetalServerNetworkAttachmentPatch

The bare metal server network attachment patch

  • curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_attachments/$network_attachment_id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The bare metal server network attachment was updated successfully.

  • 400

    An invalid bare metal server network attachment patch was provided.

  • 404

    A bare metal server network attachment with the specified identifier could not be found.

Example responses
  • {
  "$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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

BareMetalServerNetworkInterfaceCollection

Status Code

  • 200

    The bare metal server network interfaces were retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.subnet.subnet.operate

    Required for bare metal server network interfaces that specify an existing reserved IP on a subnet

  • is.subnet.subnet.update

    Required for bare metal server network interfaces that specify a new reserved IP on a subnet

  • is.security-group.security-group.operate

  • is.bare-metal-server.bare-metal-server.ip-spoofing

    Required when allow_ip_spoofing is true on any bare metal server network interface

  • is.bare-metal-server.bare-metal-server.infrastructure-nat

    Required when enable_infrastructure_nat is false on any bare metal server network interface

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

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The bare metal server network interface prototype object

  • curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces?version=2024-04-16&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

Response Body

Status Code

  • 201

    The bare metal server network interface was created successfully.

  • 400

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

  • 403

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

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

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 to true that was attached to this bare metal server network interface

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true that was attached to this bare metal server network interface

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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()

Response

Status Code

  • 204

    The bare metal server network interface was deleted successfully.

  • 403

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

  • 404

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The bare metal server network interface was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.bare-metal-server.bare-metal-server.ip-spoofing

    Required when allow_ip_spoofing is changed

  • is.bare-metal-server.bare-metal-server.infrastructure-nat

    Required when enable_infrastructure_nat is changed

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBareMetalServerNetworkInterfacePatch

The bare metal server network interface patch

  • curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/network_interfaces/$network_interface_id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The bare metal server network interface was updated successfully.

  • 400

    An invalid bare metal server network interface patch was provided.

  • 403

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

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.floating-ip.floating-ip.read

    Required for all floating IPs associated with the bare metal server network interface

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIPUnpaginatedCollection

Status Code

  • 200

    The associated floating IPs were retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

  • is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing events.

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

  • is.floating-ip.floating-ip.detach

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

  • 204

    The floating IP was disassociated successfully.

  • 400

    The specified floating IP could not be disassociated.

  • 403

    The floating IP is not allowed to be disassociated.

  • 404

    The specified floating IP address is not associated with the bare metal server network interface with the specified identifier

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

  • is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIP

Status Code

  • 200

    The associated floating IP was retrieved successfully.

  • 404

    The floating IP address is not associated with a bare metal server network interface with the specified identifier

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

  • is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing events.

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

  • is.floating-ip.floating-ip.attach

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIP

Status Code

  • 201

    The floating IP was successfully associated with the bare metal server network interface.

  • 400

    The specified floating IP could not be associated with the specified bare metal server network interface.

  • 403

    The floating IP is not allowed to be associated.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.subnet.subnet.read

    Required for the subnet attached to the bare metal server network interface

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.subnet.reserved-ip.read

    Generated for each reserved IP in the list.

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIPCollectionBareMetalServerNetworkInterfaceContext

Status Code

  • 200

    The reserved IPs were retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

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

  • is.subnet.subnet.read

    Required for the subnet attached to the bare metal server network interface

Auditing

Calling this method generates the following auditing event.

  • is.subnet.reserved-ip.read

Request

Path Parameters

  • bare_metal_server_id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • network_interface_id
    Required*
    string

    The bare metal server network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIP

Status Code

  • 200

    The bound reserved IP was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

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 to true, for each attached reserved IP

  • is.virtual-network-interface.virtual-network-interface.delete

    Generated for each virtual network interface that had auto_delete set to true

  • 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 to true

  • 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 to true

  • 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 to true

  • is.subnet.reserved-ip.delete

    Generated for each reserved IP that had auto_delete set to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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()

Response

Status Code

  • 202

    The bare metal server deletion request was accepted.

  • 403

    The bare metal server is not allowed to be deleted.

  • 404

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

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BareMetalServer

Status Code

  • 200

    The bare metal server was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBareMetalServerPatch

The bare metal server patch

  • curl -X PATCH "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id?version=2024-04-16&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

Response Body

BareMetalServer

Status Code

  • 200

    The bare metal server was updated successfully.

  • 400

    An invalid bare metal server patch was provided.

  • 403

    The bare metal server is not allowed to be updated.

  • 404

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

  • 409

    The requested update requires that the bare metal server be stopped first.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BareMetalServerInitialization

Status Code

  • 200

    The initialization configuration was retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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()

Response

Status Code

  • 204

    The restart action will run immediately.

  • 400

    The restart action could not be run.

  • 403

    The action is not allowed to be created.

  • 404

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

  • 409

    The bare metal server must not be stopped to issue a restart.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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()

Response

Status Code

  • 204

    The start action will run immediately.

  • 400

    The start action could not be run.

  • 403

    The action is not allowed to be created.

  • 404

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

  • 409

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

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The bare metal server identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
BareMetalServerStopOptions

Parameters to control the type of stop operation

  • curl -X POST "$vpc_api_endpoint/v1/bare_metal_servers/$bare_metal_server_id/stop?version=2024-04-16&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()

Response

Status Code

  • 204

    The stop action will be run immediately.

  • 400

    The stop action could not be run.

  • 403

    The action is not allowed to be created.

  • 404

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

  • 409

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

No Sample Response

This method does not specify any sample responses.

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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

VolumeProfileCollection

Status Code

  • 200

    The volume profiles were retrieved successfully

Example responses
  • {
  "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

  • name
    Required*
    string

    The volume profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VolumeProfile

Status Code

  • 200

    The volume profile was retrieved successfully

  • 404

    A volume profile with the specified name could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.volume.volume.read

Auditing

Calling this method generates the following auditing event.

  • is.volume.volume.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • name
    string

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

  • attachment_state
    string

    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

  • encryption
    string

    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

  • operating_system.family
    string

    Filters the collection to resources with an operating_system.family property matching the specified operating system family.

    This parameter also supports the values null and not: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

  • operating_system.architecture
    string

    Filters the collection to resources with an operating_system.architecture property matching the specified operating system architecture.

    This parameter also supports the values null and not:null which filter the collection to resources which have no operating system or any operating system, respectively.

    Example: amd64

  • zone.name
    string

    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

  • tag
    string

    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-16&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

Response Body

VolumeCollection

Status Code

  • 200

    The volumes were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.volume.volume.create

  • is.snapshot.snapshot.operate

    Required when source_snapshot is specified.

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.volume.volume.create

  • is.snapshot.snapshot.operate

    Required when source_snapshot is specified.

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The volume prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/volumes?version=2024-04-16&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

Response Body

Volume

Status Code

  • 201

    The volume was created successfully

  • 400

    An invalid volume prototype object was provided.

  • 409

    The volume prototype object specified an encryption key that cannot be used in its current state.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.volume.volume.delete

Auditing

Calling this method generates the following auditing event.

  • is.volume.volume.delete

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The volume identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The volume was deleted successfully.

  • 404

    A volume with the specified identifier could not be found.

  • 409

    The volume is in use and cannot be deleted.

  • 412

    The provided If-Match value does not match the current ETag value of the volume

No Sample Response

This method does not specify any sample responses.

Retrieve a volume

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

GET /volumes/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.volume.volume.read

Auditing

Calling this method generates the following auditing event.

  • is.volume.volume.read

Request

Path Parameters

  • id
    Required*
    string

    The volume identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Volume

Status Code

  • 200

    The volume was retrieved successfully

  • 404

    A volume with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.volume.volume.update

Auditing

Calling this method generates the following auditing event.

  • is.volume.volume.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The volume identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVolumePatch

The volume patch

  • curl -X PATCH "$vpc_api_endpoint/v1/volumes/$volume_id?version=2024-04-16&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

Response Body

Volume

Status Code

  • 200

    The volume was updated successfully

  • 400

    An invalid volume patch was provided.

  • 404

    A volume with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the volume

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.snapshot-consistency-group.snapshot-consistency-group.list

  • is.snapshot-consistency-group.snapshot-consistency-group.read

Auditing

Calling this method generates the following auditing event.

  • is.snapshot-consistency-group.snapshot-consistency-group.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • backup_policy_plan.id
    string

    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-16&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

Response Body

SnapshotConsistencyGroupCollection

Status Code

  • 200

    The snapshot consistency groups were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.snapshot-consistency-group.snapshot-consistency-group.create

  • is.volume.volume.operate

    Required for each source_volume specified.

  • is.instance.instance.operate

    Required for the instance attached to the source volumes.

  • is.snapshot.snapshot.create

    Required when snapshots is specified.

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot-consistency-group.snapshot-consistency-group.create

  • is.snapshot.snapshot.create

    Generated for each snapshot created

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The snapshot consistency group prototype object

  • curl -X POST "$vpc_api_endpoint/v1/snapshot_consistency_groups?version=2024-04-16&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

Response Body

SnapshotConsistencyGroup

Status Code

  • 201

    The snapshot consistency group was created successfully.

  • 400

    An invalid snapshot consistency group prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.snapshot-consistency-group.snapshot-consistency-group.delete

  • is.snapshot.snapshot.delete

    Required when delete_snapshots_on_delete property is true

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot-consistency-group.snapshot-consistency-group.delete

  • is.snapshot.snapshot.delete

    Generated for each deleted snapshot

Request

Path Parameters

  • id
    Required*
    string

    The snapshot consistency group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SnapshotConsistencyGroup

Status Code

  • 202

    The snapshot consistency group deletion request was accepted.

  • 400

    A snapshot consistency group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot-consistency-group.snapshot-consistency-group.read

Auditing

Calling this method generates the following auditing event.

  • is.snapshot-consistency-group.snapshot-consistency-group.read

Request

Path Parameters

  • id
    Required*
    string

    The snapshot consistency group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SnapshotConsistencyGroup

Status Code

  • 200

    The snapshot consistency group was retrieved successfully

  • 404

    A snapshot consistency group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot-consistency-group.snapshot-consistency-group.update

Auditing

Calling this method generates the following auditing event.

  • is.snapshot-consistency-group.snapshot-consistency-group.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The snapshot consistency group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSnapshotConsistencyGroupPatch

The snapshot consistency group patch

  • curl -X PATCH "$vpc_api_endpoint/v1/snapshot_consistency_groups/$snapshot_consistency_group_id?version=2024-04-16&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

Response Body

SnapshotConsistencyGroup

Status Code

  • 200

    The snapshot consistency group was updated successfully.

  • 400

    An invalid snapshot consistency group patch was provided.

  • 404

    A snapshot consistency group with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the snapshot consistency group

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.delete

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot.snapshot.delete

  • is.snapshot.snapshot-clone.delete

    Generated for each snapshot clone in clones[]

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • source_volume.id
    Required*
    string

    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-16&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)

Response

Status Code

  • 204

    The snapshots were deleted successfully.

  • 400

    A source volume with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.list

  • is.snapshot.snapshot.read

Auditing

Calling this method generates the following auditing events.

  • is.snapshot.snapshot.read

  • is.snapshot.snapshot-clone.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • tag
    string

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

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • source_volume.id
    string

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

  • source_volume.crn
    string

    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

  • source_image.id
    string

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

    This parameter also supports the values null and not: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_]+$

  • source_image.crn
    string

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

    This parameter also supports the values null and not: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

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • backup_policy_plan.id
    string

    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_]+$

  • copies[].id
    string

    Filters the collection to snapshots with an item in the copies property with an id property matching the specified identifier.

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • copies[].name
    string

    Filters the collection to snapshots with an item in the copies property with a 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-snapshot-copy

  • copies[].crn
    string

    Filters the collection to snapshots with an item in the copies property with an id property matching the specified CRN.

  • copies[].remote.region.name
    string

    Filters the collection to snapshots with an item in the copies property with a 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

  • source_snapshot.id
    string

    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_]+$

  • source_snapshot.remote.region.name
    string

    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

  • source_volume.remote.region.name
    string

    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

  • source_image.remote.region.name
    string

    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

  • clones[].zone.name
    string

    Filters the collection to snapshots with an item in the clones property 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

  • snapshot_consistency_group.id
    string

    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_]+$

  • snapshot_consistency_group.crn
    string

    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-16&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

Response Body

SnapshotCollection

Status Code

  • 200

    The snapshots were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.create

  • is.volume.volume.operate

  • is.instance.instance.operate

    Required for the instance the volume is attached to

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot.snapshot.create

  • is.snapshot.snapshot.capture

  • is.snapshot.snapshot-clone.create

    Generated for each snapshot clone in clones[]

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The snapshot prototype object

  • curl -X POST "$vpc_api_endpoint/v1/snapshots?version=2024-04-16&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

Response Body

Snapshot

Status Code

  • 201

    The snapshot was created successfully.

  • 400

    An invalid snapshot prototype object was provided.

  • 409

    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.
Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.delete

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot.snapshot.delete

  • is.snapshot.snapshot-clone.delete

    Generated for each snapshot clone in clones[]

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The snapshot identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The snapshot was deleted successfully.

  • 404

    A snapshot with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the snapshot

No Sample Response

This method does not specify any sample responses.

Retrieve a snapshot

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

GET /snapshots/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.read

Auditing

Calling this method generates the following auditing events.

  • is.snapshot.snapshot.read

  • is.snapshot.snapshot-clone.read

Request

Path Parameters

  • id
    Required*
    string

    The snapshot identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Snapshot

Status Code

  • 200

    The snapshot was retrieved successfully

  • 404

    A snapshot with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.update

Auditing

Calling this method generates the following auditing event.

  • is.snapshot.snapshot.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The snapshot identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSnapshotPatch

The snapshot patch

  • curl -X PATCH "$vpc_api_endpoint/v1/snapshots/$snapshot_id?version=2024-04-16&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

Response Body

Snapshot

Status Code

  • 200

    The snapshot was updated successfully.

  • 400

    An invalid snapshot patch was provided.

  • 404

    A snapshot with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the snapshot

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.read

Auditing

Calling this method generates the following auditing event.

  • is.snapshot.snapshot-clone.read

Request

Path Parameters

  • id
    Required*
    string

    The snapshot identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SnapshotCloneCollection

Status Code

  • 200

    The snapshot clones were retrieved successfully.

  • 404

    A snapshot with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot-clone.delete

  • is.snapshot.snapshot.update

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot.snapshot-clone.delete

  • is.snapshot.snapshot.update

    Generated if a snapshot clone is deleted.

Request

Path Parameters

  • id
    Required*
    string

    The snapshot identifier

  • zone_name
    Required*
    string

    The zone name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The snapshot clone deletion request was accepted.

  • 404

    A snapshot clone with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot.read

Auditing

Calling this method generates the following auditing event.

  • is.snapshot.snapshot-clone.read

Request

Path Parameters

  • id
    Required*
    string

    The snapshot identifier

  • zone_name
    Required*
    string

    The zone name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SnapshotClone

Status Code

  • 200

    The snapshot clone was retrieved successfully.

  • 404

    A snapshot clone with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.snapshot.snapshot-clone.create

  • is.snapshot.snapshot.update

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.snapshot.snapshot-clone.create

  • is.snapshot.snapshot.update

    Generated if a snapshot clone is created.

Request

Path Parameters

  • id
    Required*
    string

    The snapshot identifier

  • zone_name
    Required*
    string

    The zone name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SnapshotClone

Status Code

  • 200

    The snapshot clone was retrieved successfully.

  • 201

    The snapshot clone was created successfully.

  • 404

    A snapshot or zone with the specified identifier could not be found.

Example responses
  • {
  "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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • curl -X GET "$vpc_api_endpoint/v1/share/profiles?version=2024-04-16&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

Response Body

ShareProfileCollection

Status Code

  • 200

    The share profiles were retrieved successfully

Example responses
  • {
  "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

  • name
    Required*
    string

    The file share profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ShareProfile

Status Code

  • 200

    The share profile was retrieved successfully

  • 404

    A file share profile with the specified name could not be found.

Example responses
  • {
  "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"
}

List all file shares

This request lists all file shares in the region.

GET /shares

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.share.share.list

  • is.share.share.read

Auditing

Calling this method generates the following auditing event.

  • is.share.share.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • replication_role
    string

    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-16&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

Response Body

ShareCollection

Status Code

  • 200

    The file shares were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.share.share.create

  • is.share.share.operate

    Required when source_share is specified.

  • is.vpc.vpc.operate

  • is.virtual-network-interface.virtual-network-interface.create

    Required for share mount targets that specify a new virtual network interface

  • is.subnet.subnet.update

    Required for share mount targets that specify a new virtual network interface and a new reserved IP on a subnet

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.share.share.create

    Generated for each file share created.

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The file share prototype object

  • curl -X POST "$vpc_api_endpoint/v1/shares?version=2024-04-16&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

Response Body

Share

Status Code

  • 201

    The file share was created successfully.

  • 400

    An invalid file share prototype object was provided.

  • 409

    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 to true
    • a virtual network interface with enable_infrastructure_nat set to false
    • a virtual network interface with ips other than the primary_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
Example responses
  • {
  "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 of updating
  • 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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.delete

Auditing

Calling this method generates the following auditing event.

  • is.share.share.delete

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Share

Status Code

  • 202

    The file share deletion request was accepted.

  • 404

    A file share with the specified identifier could not be found.

  • 409

    The file share cannot be deleted in its current state.

  • 412

    The provided If-Match value does not match the current ETag value of the share

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.read

Auditing

Calling this method generates the following auditing event.

  • is.share.share.read

Request

Path Parameters

  • id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Share

Status Code

  • 200

    The file share was retrieved successfully

  • 404

    A file share with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.update

Auditing

Calling this method generates the following auditing event.

  • is.share.share.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSharePatch

The file share patch

  • curl -X PATCH "$vpc_api_endpoint/v1/shares/$id?version=2024-04-16&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

Response Body

Share

Status Code

  • 200

    The file share was updated successfully.

  • 400

    An invalid file share patch was provided.

  • 404

    A file share with the specified identifier could not be found.

  • 409

    The file share cannot update the specified properties in its current state.

  • 412

    The provided If-Match value does not match the current ETag value of the share

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.operate

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.share.share.failover

  • is.share.share.split

    Generated when fallback_policy is split and the failover request was accepted but could not be performed.

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

ShareFailoverOptions

Options to control the failover operation

  • curl -X POST "$vpc_api_endpoint/v1/shares/$share_id/failover?version=2024-04-16&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,
)

Response

Status Code

  • 202

    The file share failover request was accepted.

  • 404

    A replica file share with the specified identifier could not be found.

  • 409

    The file share cannot perform a failover in its current state.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.read

Auditing

Calling this method generates the following auditing event.

  • is.share.mount-target.list

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • name
    string

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

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

ShareMountTargetCollection

Status Code

  • 200

    The share mount targets were retrieved successfully.

  • 404

    A file share with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.share.share.update

  • is.vpc.vpc.operate

  • is.virtual-network-interface.virtual-network-interface.create

    Required for share mount targets that specify a new virtual network interface

  • is.subnet.subnet.update

    Required for share mount targets that specify a new virtual network interface and a new reserved IP on a subnet

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 is vpc.

  • 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

  • share_id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The share mount target prototype object

  • curl -X POST "$vpc_api_endpoint/v1/shares/$share_id/mount_targets?version=2024-04-16&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

Response Body

ShareMountTarget

Status Code

  • 201

    The share mount target was created successfully.

  • 400

    An invalid share mount target prototype object was provided.

  • 404

    A file share with the specified identifier could not be found.

  • 409

    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 to true
    • a virtual network interface with enable_infrastructure_nat set to false
    • a virtual network interface with ips other than the primary_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
Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.share.share.update

  • is.vpc.vpc.operate

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 is vpc

  • is.virtual-network-interface.virtual-network-interface.delete

    Generated when the virtual network interface had auto_delete set to true

  • 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 to true

  • is.subnet.reserved-ip.detach

    Generated for each reserved IP that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.reserved-ip.delete

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true that was attached to a virtual network interface that had auto_delete set to true

  • is.security-group.security-group.detach

    Generated for each security group that was attached to a virtual network interface that had auto_delete set to true

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

  • id
    Required*
    string

    The share mount target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ShareMountTarget

Status Code

  • 202

    The share mount target deletion request was accepted.

  • 404

    A share mount target with the specified identifier could not be found for the file share with the specified identifier.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.read

Auditing

Calling this method generates the following auditing event.

  • is.share.mount-target.read

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

  • id
    Required*
    string

    The share mount target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ShareMountTarget

Status Code

  • 200

    The share mount target was retrieved successfully.

  • 404

    A share mount target with the specified identifier could not be found for the file share with the specified identifier.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.update

Auditing

Calling this method generates the following auditing event.

  • is.share.mount-target.update

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

  • id
    Required*
    string

    The share mount target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonShareMountTargetPatch

The share mount target patch

  • curl -X PATCH "$vpc_api_endpoint/v1/shares/$share_id/mount_targets/$id?version=2024-04-16&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

Response Body

ShareMountTarget

Status Code

  • 200

    The share mount target was updated successfully.

  • 400

    An invalid share mount target patch was provided.

  • 404

    A share mount target with the specified identifier could not be found for the file share with the specified identifier.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.operate

Auditing

Calling this method generates the following auditing event.

  • is.share.share.split

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 202

    The file share split request was accepted.

  • 404

    A replica file share with the specified identifier could not be found.

  • 409

    The file share cannot be split in its current state.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.share.share.read

Auditing

Calling this method generates the following auditing event.

  • is.share.share.read

Request

Path Parameters

  • share_id
    Required*
    string

    The file share identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ShareReference

Status Code

  • 200

    The source file share was retrieved successfully.

  • 404

    A replica file share with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

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

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

Auditing

Calling this method generates the following auditing event.

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

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • tag
    string

    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-16&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

Response Body

BackupPolicyCollection

Status Code

  • 200

    The backup policies were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The backup policy prototype object

  • curl -X POST "$vpc_api_endpoint/v1/backup_policies?version=2024-04-16&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

Response Body

Status Code

  • 201

    The backup policy was created successfully.

  • 400

    An invalid backup policy prototype object was provided.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • backup_policy_id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • status
    string

    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]+)*$

  • backup_policy_plan.id
    string

    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_]+$

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • source.id
    string

    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_]+$

  • target_snapshots[].id
    string

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

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • target_snapshots[].crn
    string

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

    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-16&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

Response Body

BackupPolicyJobCollection

Status Code

  • 200

    The backup policy jobs were retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • backup_policy_id
    Required*
    string

    The backup policy identifier

  • id
    Required*
    string

    The backup policy job identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BackupPolicyJob

Status Code

  • 200

    The backup policy job was retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • backup_policy_id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • name
    string

    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-16&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

Response Body

BackupPolicyPlanCollection

Status Code

  • 200

    The backup policy plans were retrieved successfully.

  • 404

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

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • backup_policy_id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
BackupPolicyPlanPrototype

The backup policy plan prototype object

  • curl -X POST "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans?version=2024-04-16&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

Response Body

BackupPolicyPlan

Status Code

  • 201

    The backup policy plan was created successfully.

  • 400

    An invalid backup policy plan prototype object was provided.

  • 404

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

  • 409

    The backup policy plan prototype object specified an encryption key that cannot be used in its current state.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Custom Headers

  • If-Match
    string

    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

  • backup_policy_id
    Required*
    string

    The backup policy identifier

  • id
    Required*
    string

    The backup policy plan identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BackupPolicyPlan

Status Code

  • 202

    The backup policy plan deletion request was accepted.

  • 404

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

  • 412

    The provided If-Match value does not match the current ETag value of the backup policy plan.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • backup_policy_id
    Required*
    string

    The backup policy identifier

  • id
    Required*
    string

    The backup policy plan identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

BackupPolicyPlan

Status Code

  • 200

    The backup policy plan was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Custom Headers

  • If-Match
    string

    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

  • backup_policy_id
    Required*
    string

    The backup policy identifier

  • id
    Required*
    string

    The backup policy plan identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBackupPolicyPlanPatch

The backup policy plan patch

  • curl -X PATCH "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id/plans/$backup_policy_plan_id?version=2024-04-16&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

Response Body

BackupPolicyPlan

Status Code

  • 200

    The backup policy plan was updated successfully.

  • 400

    An invalid backup policy plan patch was provided.

  • 404

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

  • 409

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

  • 412

    The provided If-Match value does not match the current ETag value of the backup policy plan.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 202

    The backup policy deletion request was accepted.

  • 404

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

  • 412

    The provided If-Match value does not match the current ETag value of the backup policy.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Path Parameters

  • id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The backup policy was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

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

Auditing

Calling this method generates the following auditing event.

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

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The backup policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonBackupPolicyPatch

The backup policy patch

  • curl -X PATCH "$vpc_api_endpoint/v1/backup_policies/$backup_policy_id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The backup policy was updated successfully.

  • 400

    An invalid backup policy patch was provided.

  • 404

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

  • 412

    The provided If-Match value does not match the current ETag value of the backup policy.

Example responses
  • {
  "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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

RegionCollection

Status Code

  • 200

    The regions were retrieved successfully.

Example responses
  • {
  "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

  • name
    Required*
    string

    The region name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Region

Status Code

  • 200

    The region was retrieved successfully.

  • 404

    A region with the specified name could not be found.

Example responses
  • {
  "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

  • region_name
    Required*
    string

    The region name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ZoneCollection

Status Code

  • 200

    The zones were retrieved successfully.

  • 404

    A region with the specified name could not be found.

Example responses
  • {
  "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

  • region_name
    Required*
    string

    The region name

  • name
    Required*
    string

    The zone name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Zone

Status Code

  • 200

    The zone was retrieved successfully.

  • 404

    A zone with the specified name could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.list

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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-16&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

Response Body

VirtualNetworkInterfaceCollection

Status Code

  • 200

    The virtual network interfaces were retrieved successfully.

Example responses
  • {
  "$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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.create

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required when allow_ip_spoofing is true

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required when enable_infrastructure_nat is false

  • is.security-group.security-group.operate

  • is.subnet.subnet.operate

    Required for virtual network interfaces that specify an existing reserved IP on a subnet

  • is.subnet.subnet.update

    Required for virtual network interfaces that specify a new reserved IP on a subnet

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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
VirtualNetworkInterfacePrototype

The virtual network interface prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/virtual_network_interfaces?version=2024-04-16&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

Response Body

VirtualNetworkInterface

Status Code

  • 201

    The virtual network interface was created successfully.

  • 400

    An invalid virtual network interface prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.delete

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 to true

  • is.subnet.subnet.update

    Generated for each reserved IP that had auto_delete set to true

  • 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 to true was attached to the virtual network interface

  • is.flow-log-collector.flow-log-collector.detach

    Generated if a flow log collector is detached from the virtual network interface

Request

Path Parameters

  • id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 202

    The virtual network interface deletion request was accepted.

  • 403

    The specified virtual network interface is owned by the provider.

  • 404

    The specified virtual network interface could not be found.

  • 409

    The virtual network interface is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.read

Request

Path Parameters

  • id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VirtualNetworkInterface

Status Code

  • 200

    The virtual network interface was retrieved successfully.

  • 404

    The specified virtual network interface could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.update

  • is.virtual-network-interface.virtual-network-interface.manage-ip-spoofing

    Required when updating allow_ip_spoofing to or from true

  • is.virtual-network-interface.virtual-network-interface.manage-infrastructure-nat

    Required when updating enable_infrastructure_nat to or from false

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.update

Request

Path Parameters

  • id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVirtualNetworkInterfacePatch

The virtual network interface patch

  • curl -X PATCH "$vpc_api_endpoint/v1/virtual_network_interfaces/$network_interface_id?version=2024-04-16&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

Response Body

VirtualNetworkInterface

Status Code

  • 200

    The virtual network interface was updated successfully.

  • 400

    An invalid virtual network interface patch was provided.

  • 403

    The specified virtual network interface is owned by the provider.

  • 404

    A virtual network interface with the specified identifier could not be found.

  • 409

    The virtual network interface's allow_ip_spoofing property cannot be true when target specifies a share mount target.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.read

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

    Sorts the returned collection by the specified property name in ascending order. A - may be prepended to the name to sort in descending order. For example, the value -name sorts the collection by the name property in descending order, and the value name sorts it by the name 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-16&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

Response Body

FloatingIPCollectionVirtualNetworkInterfaceContext

Status Code

  • 200

    The associated floating IPs were retrieved successfully.

  • 404

    A virtual network interface with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.operate

  • is.floating-ip.floating-ip.operate

Auditing

Calling this method generates the following auditing events.

  • is.virtual-network-interface.virtual-network-interface.detach

  • is.floating-ip.floating-ip.detach

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 204

    The floating IP was disassociated successfully.

  • 400

    The specified floating IP could not be disassociated.

  • 404

    The specified floating IP is not associated with the virtual network interface with the specified identifier

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.read

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIPReference

Status Code

  • 200

    The associated floating IP was retrieved successfully.

  • 404

    The floating IP is not associated with a virtual network interface with the specified identifier

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.operate

  • is.floating-ip.floating-ip.operate

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

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIPReference

Status Code

  • 200

    The specified floating IP is already associated with the virtual network interface.

  • 201

    The floating IP was successfully associated with the virtual network interface.

  • 400

    The specified floating IP could not be associated with the specified virtual network interface.

  • 404

    The specified virtual network interface or floating IP could not be found.

  • 409

    The request specified one or more of:

    • a floating IP associated with another resource
    • a virtual network interface that has enable_infrastructure_nat set to true and another floating IP associated with it
    • a virtual network interface whose target is a file share mount target
Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.virtual-network-interface.virtual-network-interface.read

    Generated for each reserved IP in the list.

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

    Sorts the returned collection by the specified property name in ascending order. A - may be prepended to the name to sort in descending order. For example, the value -name sorts the collection by the name property in descending order, and the value name sorts it by the name 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-16&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

Response Body

ReservedIPCollectionVirtualNetworkInterfaceContext

Status Code

  • 200

    The reserved IPs were retrieved successfully.

  • 404

    A virtual network interface with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.operate

  • is.subnet.subnet.operate

    Required for the subnet attached to the virtual network interface

Auditing

Calling this method generates the following auditing events.

  • is.virtual-network-interface.virtual-network-interface.detach

  • is.subnet.reserved-ip.detach

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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,
)

Response

Status Code

  • 204

    The reserved IP was unbound successfully.

  • 400

    The primary reserved IP address cannot be unbound.

  • 404

    The specified reserved IP address is not associated with the virtual network interface with the specified identifier

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.read

Auditing

Calling this method generates the following auditing event.

  • is.virtual-network-interface.virtual-network-interface.read

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIPReference

Status Code

  • 200

    The associated reserved IP was retrieved successfully.

  • 404

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

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.virtual-network-interface.virtual-network-interface.operate

  • is.subnet.subnet.operate

    Required for the subnet attached to the virtual network interface

Auditing

Calling this method generates the following auditing events.

  • is.virtual-network-interface.virtual-network-interface.attach

  • is.subnet.reserved-ip.attach

Request

Path Parameters

  • virtual_network_interface_id
    Required*
    string

    The virtual network interface identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIPReference

Status Code

  • 200

    The specified reserved IP is already bound to the virtual network interface.

  • 201

    The reserved IP was successfully bound to the virtual network interface.

  • 400

    The specified reserved IP is not in the primary IP's subnet.

  • 404

    A virtual network interface with the specified identifier could not be found.

  • 409

    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
Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.public-gateway.public-gateway.list

  • is.public-gateway.public-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.public-gateway.public-gateway.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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-16&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

Response Body

PublicGatewayCollection

Status Code

  • 200

    The public gateways were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.public-gateway.public-gateway.create

  • is.vpc.vpc.operate

  • is.floating-ip.floating-ip.create

    Required when floating_ip specifies a new floating IP

  • is.floating-ip.floating-ip.operate

    Required when floating_ip specifies an existing floating IP

Auditing

Calling this method generates the following auditing event.

  • is.public-gateway.public-gateway.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
PublicGatewayPrototype

The public gateway prototype object

  • curl -X POST "$vpc_api_endpoint/v1/public_gateways?version=2024-04-16&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

Response Body

PublicGateway

Status Code

  • 201

    The public gateway was created successfully.

  • 400

    An invalid public gateway prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.public-gateway.public-gateway.delete

Auditing

Calling this method generates the following auditing event.

  • is.public-gateway.public-gateway.delete

Request

Path Parameters

  • id
    Required*
    string

    The public gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The public gateway was deleted successfully.

  • 404

    A public gateway with the specified identifier could not be found.

  • 409

    The public gateway is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a public gateway

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

GET /public_gateways/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.public-gateway.public-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.public-gateway.public-gateway.read

Request

Path Parameters

  • id
    Required*
    string

    The public gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

PublicGateway

Status Code

  • 200

    The public gateway was retrieved successfully.

  • 404

    A public gateway with the specified identifier could not be found.

Example responses
  • {
  "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"
  }
}

Update a public gateway

This request updates a public gateway's name.

PATCH /public_gateways/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.public-gateway.public-gateway.update

Auditing

Calling this method generates the following auditing event.

  • is.public-gateway.public-gateway.update

Request

Path Parameters

  • id
    Required*
    string

    The public gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonPublicGatewayPatch

The public gateway patch

  • curl -X PATCH "$vpc_api_endpoint/v1/public_gateways/$public_gateway_id?version=2024-04-16&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

Response Body

PublicGateway

Status Code

  • 200

    The public gateway was updated successfully.

  • 400

    An invalid public gateway patch was provided.

  • 404

    A public gateway with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.floating-ip.floating-ip.list

  • is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

  • is.floating-ip.floating-ip.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • target.id
    string

    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_]+$

  • target.crn
    string

    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

  • target.name
    string

    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

  • target.resource_type
    string

    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-16&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

Response Body

FloatingIPCollection

Status Code

  • 200

    The floating IPs were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.floating-ip.floating-ip.create

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

    Required when target specifies a bare metal server network interface

  • is.instance.instance.operate

    Required when target specifies an instance network interface

  • is.virtual-network-interface.virtual-network-interface.operate

    Required when target specifies a virtual network interface

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 specified

  • is.instance.network-interface.attach

    Generated when target specifies an instance network interface

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

    Generated when target specifies a bare metal server network interface

  • is.virtual-network-interface.virtual-network-interface.attach

    Generated when target specifies a virtual network interface

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The floating IP prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/floating_ips?version=2024-04-16&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

Response Body

FloatingIP

Status Code

  • 201

    The floating IP was reserved successfully.

  • 400

    An invalid floating IP prototype object was provided.

  • 409

    The specified target already has a floating IP bound to it.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.floating-ip.floating-ip.delete

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

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The floating IP was deleted successfully.

  • 404

    The specified floating IP could not be found.

  • 409

    The floating IP is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a floating IP

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

GET /floating_ips/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.floating-ip.floating-ip.read

Auditing

Calling this method generates the following auditing event.

  • is.floating-ip.floating-ip.read

Request

Path Parameters

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FloatingIP

Status Code

  • 200

    The floating IP was retrieved successfully.

  • 404

    The specified floating IP could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.floating-ip.floating-ip.update

  • is.floating-ip.floating-ip.operate

    Required when target is specified

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

    Required when target is changed to or from a bare metal server network interface

  • is.instance.instance.operate

    Required when target is changed to or from an instance network interface

  • is.virtual-network-interface.virtual-network-interface.operate

    Required when target is changed to or from a virtual network interface

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 specified

  • is.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 interface

  • is.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 interface

  • is.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 interface

  • is.virtual-network-interface.virtual-network-interface.detach

    Generated when an existing virtual network interface target is replaced

Request

Path Parameters

  • id
    Required*
    string

    The floating IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonFloatingIPPatch

The floating IP patch

  • curl -X PATCH "$vpc_api_endpoint/v1/floating_ips/$floating_ip_id?version=2024-04-16&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

Response Body

FloatingIP

Status Code

  • 200

    The floating IP was updated successfully.

  • 400

    An invalid floating IP patch was provided.

  • 404

    A floating IP with the specified identifier could not be found.

  • 409

    The floating IP is required by another resource, or the specified target already has a floating IP bound to it.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.list

  • is.network-acl.network-acl.read

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.network-acl.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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-16&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

Response Body

NetworkACLCollection

Status Code

  • 200

    The network ACLs were retrieved successfully

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.create

  • is.network-acl.network-acl.read

    Required when source_network_acl is specified

  • is.vpc.vpc.operate

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.network-acl.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The network ACL prototype object

Examples:
View
  • curl -X POST   "$vpc_api_endpoint/v1/network_acls?version=2024-04-16&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: &copyableAclID,
  },
  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

Response Body

NetworkACL

Status Code

  • 201

    The network ACL was created successfully

  • 400

    An invalid network ACL prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.delete

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.network-acl.delete

Request

Path Parameters

  • id
    Required*
    string

    The network ACL identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The network ACL was deleted successfully.

  • 403

    A default network ACL is not allowed to be deleted.

  • 404

    A network ACL with the specified identifier could not be found.

  • 409

    The network ACL is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a network ACL

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

GET /network_acls/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.read

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.network-acl.read

Request

Path Parameters

  • id
    Required*
    string

    The network ACL identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

NetworkACL

Status Code

  • 200

    The network ACL was retrieved successfully

  • 404

    A network ACL with the specified identifier could not be found.

Example responses
  • {
  "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"
  }
}

Update a network ACL

This request updates a network ACL's name.

PATCH /network_acls/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.update

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.network-acl.update

Request

Path Parameters

  • id
    Required*
    string

    The network ACL identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonNetworkACLPatch

The network ACL patch

  • curl -X PATCH "$vpc_api_endpoint/v1/network_acls/$network_acl_id?version=2024-04-16&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

Response Body

NetworkACL

Status Code

  • 200

    The network ACL was updated successfully.

  • 400

    An invalid network ACL patch was provided.

  • 404

    A network ACL with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.read

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.rule.read

Request

Path Parameters

  • network_acl_id
    Required*
    string

    The network ACL identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • direction
    string

    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-16&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

Response Body

NetworkACLRuleCollection

Status Code

  • 200

    The network ACL rules were retrieved successfully.

  • 404

    A network ACL with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.update

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.rule.create

Request

Path Parameters

  • network_acl_id
    Required*
    string

    The network ACL identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The network ACL rule prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules?version=2024-04-16&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

Response Body

Status Code

  • 201

    The network ACL rule was created successfully.

  • 400

    An invalid network ACL rule prototype object was provided.

  • 404

    A network ACL with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.update

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.rule.delete

Request

Path Parameters

  • network_acl_id
    Required*
    string

    The network ACL identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The network ACL rule was deleted successfully.

  • 404

    A network ACL rule with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.read

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.rule.read

Request

Path Parameters

  • network_acl_id
    Required*
    string

    The network ACL identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The network ACL rule was retrieved successfully.

  • 404

    A network ACL rule with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.network-acl.network-acl.update

Auditing

Calling this method generates the following auditing event.

  • is.network-acl.rule.update

Request

Path Parameters

  • network_acl_id
    Required*
    string

    The network ACL identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonNetworkACLRulePatch

The network ACL rule patch

  • curl -X PATCH "$vpc_api_endpoint/v1/network_acls/$network_acl_id/rules/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The network ACL rule was updated successfully.

  • 400

    An invalid network ACL rule patch was provided.

  • 404

    A network ACL rule with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.list

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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-16&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

Response Body

SecurityGroupCollection

Status Code

  • 200

    The security groups were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.create

  • is.vpc.vpc.operate

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
SecurityGroupPrototype

The security group prototype object

  • curl -X POST "$vpc_api_endpoint/v1/security_groups?version=2024-04-16&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

Response Body

SecurityGroup

Status Code

  • 201

    The security group was created successfully.

  • 400

    An invalid security group prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.delete

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.delete

Request

Path Parameters

  • id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The security group was deleted successfully.

  • 403

    The VPC's default security group is not allowed to be deleted.

  • 404

    A security group with the specified identifier could not be found.

  • 409

    The security group is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a security group

This request retrieves a single security group specified by the identifier in the URL path.

GET /security_groups/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.read

Request

Path Parameters

  • id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SecurityGroup

Status Code

  • 200

    The security group was retrieved successfully.

  • 404

    A security group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.update

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.update

Request

Path Parameters

  • id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSecurityGroupPatch

The security group patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/security_groups/$security_group_id?version=2024-04-16&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

Response Body

SecurityGroup

Status Code

  • 200

    The security group was updated successfully.

  • 400

    An invalid security group patch was provided.

  • 404

    A security group with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group-rule.read

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

SecurityGroupRuleCollection

Collection of rules in a security group

Status Code

  • 200

    The security group rules were retrieved successfully.

  • 404

    A security group with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.update

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group-rule.create

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The properties of the security group rule to be created.

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules?version=2024-04-16&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

Response Body

Status Code

  • 201

    The security group rule was created successfully.

  • 400

    An invalid security group rule prototype object was provided.

  • 404

    A security group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.update

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group-rule.delete

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The security group rule was deleted successfully.

  • 404

    A rule with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group-rule.read

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The rule was retrieved successfully.

  • 404

    A rule with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.update

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group-rule.update

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonSecurityGroupRulePatch

The security group rule patch.

Examples:
View
  • curl -X PATCH "$vpc_api_endpoint/v1/security_groups/$security_group_id/rules/$id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The security group rule was updated successfully.

  • 400

    An invalid security group rule patch was provided.

  • 404

    A rule with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.read

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

SecurityGroupTargetCollection

Status Code

  • 200

    The targets were retrieved successfully.

  • 404

    A security group with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.operate

  • is.instance.instance.operate

    Required when target specifies an instance network interface

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

    Required when target specifies a bare metal server network interface

  • is.virtual-network-interface.virtual-network-interface.operate

    Required when target specifies a virtual network interface

  • is.load-balancer.load-balancer.manage

    Required when target specifies a load balancer

  • is.endpoint-gateway.endpoint-gateway.operate

    Required when target specifies an endpoint gateway

  • is.vpn-server.vpn-server.operate

    Required when target specifies a VPN server

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 gateway

  • is.instance.network-interface.update

    Generated when target specifies an instance network interface

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

    Generated when target specifies a bare metal server network interface

  • is.load-balancer.load-balancer.update

    Generated when target specifies a load balancer

  • is.vpn-server.vpn-server.update

    Generated when target specifies a VPN server

  • is.security-group.security-group.detach

  • is.virtual-network-interface.virtual-network-interface.detach

    Generated when target specifies a virtual network interface

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The security group target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

  • 204

    The target was successfully removed from the security group.

  • 404

    The specified target was not in the specified security group.

  • 409

    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

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.read

Auditing

Calling this method generates the following auditing event.

  • is.security-group.security-group.read

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The security group target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

One of

A target of this security group.

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

Status Code

  • 200

    The target was retrieved successfully.

  • 404

    The specified target or security group could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.security-group.security-group.operate

  • is.instance.instance.operate

    Required when target specifies an instance network interface

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

    Required when target specifies a bare metal server network interface

  • is.virtual-network-interface.virtual-network-interface.operate

    Required when target specifies a virtual network interface

  • is.load-balancer.load-balancer.manage

    Required when target specifies a load balancer

  • is.endpoint-gateway.endpoint-gateway.operate

    Required when target specifies an endpoint gateway

  • is.vpn-server.vpn-server.operate

    Required when target specifies a VPN server

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 gateway

  • is.instance.network-interface.update

    Generated when target specifies an instance network interface

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

    Generated when target specifies a bare metal server network interface

  • is.load-balancer.load-balancer.update

    Generated when target specifies a load balancer

  • is.vpn-server.vpn-server.update

    Generated when target specifies a VPN server

  • is.security-group.security-group.attach

  • is.virtual-network-interface.virtual-network-interface.attach

    Generated when target specifies a virtual network interface

Request

Path Parameters

  • security_group_id
    Required*
    string

    The security group identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

  • id
    Required*
    string

    The security group target identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

One of

A target of this security group.

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

Status Code

  • 200

    The specified target is already in the security group.

  • 201

    The target was successfully added to the security group

  • 400

    The specified target is not in the same VPC, or has reached its security group limit.

  • 404

    The specified target or security group could not be found.

  • 409

    The specified target cannot be updated in its current state.

    Applicable to application load balancer targets that do not have an active provisioning status.

Example responses
  • {
  "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"
}

List all IKE policies

This request lists all IKE policies in the region.

GET /ike_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ike-policy.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

IKEPolicyCollection

Status Code

  • 200

    The IKE policies were retrieved successfully.

Example responses
  • {
  "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
}

Create an IKE policy

This request creates a new IKE policy.

POST /ike_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ike-policy.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
IKEPolicyPrototype

The IKE policy prototype object.

  • curl -X POST "$vpc_api_endpoint/v1/ike_policies?version=2024-04-16&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

Response Body

IKEPolicy

Status Code

  • 201

    The IKE policy was created successfully.

  • 400

    An invalid IKE policy prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ike-policy.delete

Request

Path Parameters

  • id
    Required*
    string

    The IKE policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The IKE policy was deleted successfully.

  • 404

    An IKE policy with the specified identifier could not be found.

  • 409

    The IKE policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve an IKE policy

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

GET /ike_policies/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ike-policy.read

Request

Path Parameters

  • id
    Required*
    string

    The IKE policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

IKEPolicy

Status Code

  • 200

    The IKE policy was retrieved successfully.

  • 404

    An IKE policy with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ike-policy.update

Request

Path Parameters

  • id
    Required*
    string

    The IKE policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonIKEPolicyPatch

The IKE policy patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/ike_policies/$ike_policy_id?version=2024-04-16&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

Response Body

IKEPolicy

Status Code

  • 200

    The IKE policy was updated successfully.

  • 400

    An invalid IKE policy patch was provided.

  • 404

    An IKE policy with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.list

Request

Path Parameters

  • id
    Required*
    string

    The IKE policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Response Body

VPNGatewayConnectionCollection

Collection of VPN gateway connections in a VPN gateway

Status Code

  • 200

    The VPN gateway connections were retrieved successfully.

  • 404

    A policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all IPsec policies

This request lists all IPsec policies in the region.

GET /ipsec_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ipsec-policy.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

IPsecPolicyCollection

Status Code

  • 200

    The IPsec policies were retrieved successfully.

Example responses
  • {
  "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
}

Create an IPsec policy

This request creates a new IPsec policy.

POST /ipsec_policies

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ipsec-policy.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
IPsecPolicyPrototype

The IPsec policy prototype object.

  • curl -X POST "$vpc_api_endpoint/v1/ipsec_policies?version=2024-04-16&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

Response Body

IPsecPolicy

Status Code

  • 201

    The IPsec policy was created successfully.

  • 400

    An invalid IPsec policy prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ipsec-policy.delete

Request

Path Parameters

  • id
    Required*
    string

    The IPsec policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The IPsec policy was deleted successfully.

  • 404

    An IPsec policy with the specified identifier could not be found.

  • 409

    The IPsec policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve an IPsec policy

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

GET /ipsec_policies/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ipsec-policy.read

Request

Path Parameters

  • id
    Required*
    string

    The IPsec policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

IPsecPolicy

Status Code

  • 200

    The IPsec policy was retrieved successfully.

  • 404

    An IPsec policy with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn.ipsec-policy.update

Request

Path Parameters

  • id
    Required*
    string

    The IPsec policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonIPsecPolicyPatch

The IPsec policy patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2024-04-16&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

Response Body

IPsecPolicy

Status Code

  • 200

    The IPsec policy was updated successfully.

  • 400

    An invalid IPsec policy patch was provided.

  • 404

    An IPsec policy with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.list

Request

Path Parameters

  • id
    Required*
    string

    The IPsec policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Response Body

VPNGatewayConnectionCollection

Collection of VPN gateway connections in a VPN gateway

Status Code

  • 200

    The VPN gateway connections were retrieved successfully.

  • 404

    A policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all VPN gateways

This request lists all VPN gateways in the region.

GET /vpn_gateways

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-gateway.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • mode
    string

    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-16&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

Response Body

VPNGatewayCollection

Status Code

  • 200

    The VPN gateways were retrieved successfully.

Example responses
  • {
  "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"
      }
    }
  ]
}

Create a VPN gateway

This request creates a new VPN gateway.

POST /vpn_gateways

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-gateway.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The VPN gateway prototype object.

  • curl -X POST "$vpc_api_endpoint/v1/vpn_gateways?version=2024-04-16&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

Response Body

Status Code

  • 201

    The VPN gateway was created successfully.

  • 400

    An invalid VPN gateway prototype object was provided.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-gateway.delete

Request

Path Parameters

  • id
    Required*
    string

    The VPN gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The VPN gateway deletion request was accepted.

  • 403

    The VPN gateway is not allowed to be deleted.

  • 404

    A VPN gateway with the specified identifier could not be found.

  • 409

    The VPN gateway is not allowed to be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve a VPN gateway

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

GET /vpn_gateways/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-gateway.read

Request

Path Parameters

  • id
    Required*
    string

    The VPN gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The VPN gateway was retrieved successfully.

  • 404

    A VPN gateway with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-gateway.update

Request

Path Parameters

  • id
    Required*
    string

    The VPN gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPNGatewayPatch

The VPN gateway patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The VPN gateway was updated successfully.

  • 400

    An invalid VPN gateway patch was provided.

  • 403

    The VPN gateway is not allowed to be updated.

  • 404

    A VPN gateway with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.list

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • status
    string

    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-16&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

Response Body

VPNGatewayConnectionCollection

Collection of VPN gateway connections in a VPN gateway

Status Code

  • 200

    The VPN gateway connections were retrieved successfully.

  • 404

    A VPN gateway with the specified identifier could not be found.

Example responses
  • {
  "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
      },
      "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.50/24"
      ],
      "mode": "policy",
      "name": "my-vpn-connection-1",
      "peer_address": "192.0.2.5",
      "peer_cidrs": [
        "192.0.2.40/24"
      ],
      "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
      },
      "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.50/24"
      ],
      "mode": "policy",
      "name": "my-vpn-connection-2",
      "peer_address": "192.0.2.5",
      "peer_cidrs": [
        "192.0.2.40/24"
      ],
      "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.create

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*

The VPN gateway connection prototype object.

  • curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2024-04-16&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_address": "192.0.2.5",
      "peer_cidrs": ["192.0.2.40/24"],
      "psk": "lkj14b1oi0alcniejkso"
    }'
  • options := &vpcv1.CreateVPNGatewayConnectionOptions{}
options.SetName(name)
options.SetVPNGatewayID(gatewayID)
options.SetPeerAddress(peerAddress)
options.SetPsk("lkj14b1oi0alcniejkso")
local := []string{"192.132.0.0/28"}
options.SetLocalCidrs(local)
peer := []string{"197.155.0.0/28"}
options.SetPeerCidrs(peer)
vpnGatewayConnection, response, err := vpcService.CreateVPNGatewayConnection(
  options
)
  • CreateVpnGatewayConnectionOptions createVpnGatewayConnectionOptions = new CreateVpnGatewayConnectionOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .peerAddress("169.21.50.5")
  .psk("lkj14b1oi0alcniejkso")
  .name("my-vpn-connection")
  .build();

Response<VPNGatewayConnection> response = service.createVpnGatewayConnection(createVpnGatewayConnectionOptions).execute();
VPNGatewayConnection vpnGatewayConnection = response.getResult();
  • const params = {
  vpnGatewayId,
  peerAddress: '169.21.50.5',
  psk: 'lkj14b1oi0alcniejkso',
  name: 'my-vpn-connection',
};
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

peer_address = '169.21.50.5'
psk = 'my-password'
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
local_cidrs = ['192.168.1.0/24']
name = 'my-vpn-connection'
peer_cidrs = ['10.45.1.0/24']

response = service.create_vpn_gateway_connection(
    vpn_gateway_id,
    peer_address,
    psk,
    admin_state_up=admin_state_up,
    dead_peer_detection=dead_peer_detection,
    ike_policy=ike_policy,
    ipsec_policy=ipsec_policy,
    local_cidrs=local_cidrs,
    name=name,
    peer_cidrs=peer_cidrs,
)

Response

Response Body

Status Code

  • 201

    The VPN gateway connection was created successfully.

  • 400

    An invalid VPN gateway connection prototype object was provided.

  • 403

    The VPN gateway connection is not allowed to be created.

Example responses
  • {
  "admin_state_up": true,
  "authentication_mode": "psk",
  "created_at": "2018-12-13T19:39:47.938464Z",
  "dead_peer_detection": {
    "action": "none",
    "interval": 15,
    "timeout": 30
  },
  "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.50/24"
  ],
  "mode": "policy",
  "name": "my-vpn-connection-2",
  "peer_address": "192.0.2.5",
  "peer_cidrs": [
    "192.0.2.40/24"
  ],
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.delete

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The VPN gateway connection deletion request was accepted.

  • 403

    The VPN gateway connection is not allowed to be deleted.

  • 404

    A VPN gateway connection with the specified identifier could not be found.

  • 409

    The VPN gateway connection is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.read

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

Status Code

  • 200

    The VPN gateway connection was retrieved successfully.

  • 404

    A VPN gateway connection with the specified identifier could not be found.

Example responses
  • {
  "admin_state_up": true,
  "authentication_mode": "psk",
  "created_at": "2018-12-13T19:40:12.124082Z",
  "dead_peer_detection": {
    "action": "none",
    "interval": 15,
    "timeout": 30
  },
  "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.50/24"
  ],
  "mode": "policy",
  "name": "my-vpn-connection-1",
  "peer_address": "192.0.2.5",
  "peer_cidrs": [
    "192.0.2.40/24"
  ],
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection.update

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPNGatewayConnectionPatch

The VPN gateway connection patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2024-04-16&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

Response Body

Status Code

  • 200

    The VPN gateway connection was updated successfully.

  • 400

    An invalid VPN gateway connection patch was provided.

  • 403

    The VPN gateway connection is not allowed to be updated.

  • 404

    A VPN gateway connection with the specified identifier could not be found.

Example responses
  • {
  "admin_state_up": true,
  "authentication_mode": "psk",
  "created_at": "2018-12-13T19:40:12.124082Z",
  "dead_peer_detection": {
    "action": "none",
    "interval": 15,
    "timeout": 30
  },
  "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.50/24"
  ],
  "mode": "policy",
  "name": "my-vpn-connection-1",
  "peer_address": "192.0.2.5",
  "peer_cidrs": [
    "192.0.2.40/24"
  ],
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-local-cidr.list

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.ListVPNGatewayConnectionLocalCidrsOptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
localCIDRs, response, err :=
  vpcService.ListVPNGatewayConnectionLocalCidrs(options)
  • ListVpnGatewayConnectionLocalCidrsOptions listVpnGatewayConnectionLocalCidrsOptions = new ListVpnGatewayConnectionLocalCidrsOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .build();

Response<VPNGatewayConnectionLocalCIDRs> response = service.listVpnGatewayConnectionLocalCidrs(listVpnGatewayConnectionLocalCidrsOptions).execute();
VPNGatewayConnectionLocalCIDRs vpnGatewayConnectionLocalCidRs = response.getResult();
  • const response = await vpcService.listVpnGatewayConnectionLocalCidrs({
  vpnGatewayId,
  id,
});
  • response = service.list_vpn_gateway_connection_local_cidrs(
  vpn_gateway_id, id)

Response

Response Body

VPNGatewayConnectionLocalCIDRs

Status Code

  • 200

    The CIDRs were retrieved successfully.

  • 404

    A VPN gateway connection with the specified identifier could not be found.

Example responses
  • {
  "local_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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-local-cidr.delete

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.RemoveVPNGatewayConnectionLocalCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.RemoveVPNGatewayConnectionLocalCIDR(options)
  • RemoveVpnGatewayConnectionLocalCidrOptions removeVpnGatewayConnectionLocalCidrOptions = new RemoveVpnGatewayConnectionLocalCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();

Response<Void> response = service.removeVpnGatewayConnectionLocalCidr(removeVpnGatewayConnectionLocalCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};
const response = await vpcService.removeVpnGatewayConnectionLocalCidr(params);
  • response = service.remove_vpn_gateway_connection_local_cidr(
  vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The CIDR was successfully removed from the specified VPN gateway connection.

  • 400

    The last CIDR could not be removed from the specified VPN gateway connection.

  • 403

    The CIDR is not allowed to be removed from the specified VPN gateway connection.

  • 404

    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

This method does not specify any sample responses.

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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-local-cidr.read

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.CheckVPNGatewayConnectionLocalCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.CheckVPNGatewayConnectionLocalCIDR(options)
  • CheckVpnGatewayConnectionLocalCidrOptions checkVpnGatewayConnectionLocalCidrOptions = new CheckVpnGatewayConnectionLocalCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();

Response<Void> response = service.checkVpnGatewayConnectionLocalCidr(checkVpnGatewayConnectionLocalCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};

const response = await vpcService.checkVpnGatewayConnectionLocalCidr(params);
  • response = service.check_vpn_gateway_connection_local_cidr(
  vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The specified CIDR exists on the specified VPN gateway connection.

  • 404

    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

This method does not specify any sample responses.

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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-local-cidr.create

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.AddVPNGatewayConnectionLocalCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.AddVPNGatewayConnectionLocalCIDR(options)
  • AddVpnGatewayConnectionLocalCidrOptions addVpnGatewayConnectionLocalCidrOptions = new AddVpnGatewayConnectionLocalCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();

Response<Void> response = service.addVpnGatewayConnectionLocalCidr(addVpnGatewayConnectionLocalCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};
const response = await vpcService.addVpnGatewayConnectionLocalCidr(params);
  • response = service.add_vpn_gateway_connection_local_cidr(
  vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The CIDR was successfully set on the specified VPN gateway connection.

  • 400

    The specified CIDR was invalid.

  • 403

    The CIDR is not allowed to be set on the specified VPN gateway connection.

  • 404

    The specified VPN gateway connection could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.list

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-peer-cidr.list

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.ListVPNGatewayConnectionPeerCidrsOptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
peerCIDRs, response, err :=
  vpcService.ListVPNGatewayConnectionPeerCidrs(options)
  • ListVpnGatewayConnectionPeerCidrsOptions listVpnGatewayConnectionPeerCidrsOptions = new ListVpnGatewayConnectionPeerCidrsOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .build();

Response<VPNGatewayConnectionPeerCIDRs> response = service.listVpnGatewayConnectionPeerCidrs(listVpnGatewayConnectionPeerCidrsOptions).execute();
VPNGatewayConnectionPeerCIDRs vpnGatewayConnectionPeerCidRs = response.getResult();
  • const response = await vpcService.listVpnGatewayConnectionPeerCidrs({
  id,
  vpnGatewayId,
});
  • response = service.list_vpn_gateway_connection_peer_cidrs(
  vpn_gateway_id, id)

Response

Response Body

VPNGatewayConnectionPeerCIDRs

Status Code

  • 200

    The CIDRs were retrieved successfully.

  • 404

    A VPN gateway connection with the specified identifier could not be found.

Example responses
  • {
  "peer_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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-peer-cidr.delete

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.RemoveVPNGatewayConnectionPeerCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.RemoveVPNGatewayConnectionPeerCIDR(options)
  • RemoveVpnGatewayConnectionPeerCidrOptions removeVpnGatewayConnectionPeerCidrOptions = new RemoveVpnGatewayConnectionPeerCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();

Response<Void> response = service.removeVpnGatewayConnectionPeerCidr(removeVpnGatewayConnectionPeerCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};

const response = await vpcService.removeVpnGatewayConnectionPeerCidr(params);
  • response = service.remove_vpn_gateway_connection_peer_cidr(
  vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The CIDR was successfully removed from the specified VPN gateway connection.

  • 400

    The last CIDR could not be removed from the specified VPN gateway connection.

  • 403

    The CIDR is not allowed to be removed from the specified VPN gateway connection.

  • 404

    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

This method does not specify any sample responses.

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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-peer-cidr.read

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.CheckVPNGatewayConnectionPeerCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.CheckVPNGatewayConnectionPeerCIDR(options)
  • CheckVpnGatewayConnectionPeerCidrOptions checkVpnGatewayConnectionPeerCidrOptions = new CheckVpnGatewayConnectionPeerCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();

Response<Void> response = service.checkVpnGatewayConnectionPeerCidr(checkVpnGatewayConnectionPeerCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};

const response = await vpcService.checkVpnGatewayConnectionPeerCidr(params);
  • response = service.check_vpn_gateway_connection_peer_cidr(
    vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The specified CIDR exists on the specified VPN gateway connection.

  • 404

    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

This method does not specify any sample responses.

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_prefix}/{prefix_length}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.vpn.vpn.read

  • is.vpn.vpn.create

Auditing

Calling this method generates the following auditing event.

  • is.vpn.vpn-connection-peer-cidr.create

Request

Path Parameters

  • vpn_gateway_id
    Required*
    string

    The VPN gateway identifier

  • id
    Required*
    string

    The VPN gateway connection identifier

  • cidr_prefix
    Required*
    string

    The address prefix part of the CIDR

  • prefix_length
    Required*
    string

    The prefix length part of the CIDR

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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_prefix/$prefix_length?version=2024-04-16&generation=2&maturity=beta" -H "Authorization: Bearer $iam_token"
  • options := &vpcv1.AddVPNGatewayConnectionPeerCIDROptions{}
options.SetVPNGatewayID(gatewayID)
options.SetID(connID)
options.SetCIDRPrefix(prefixAdd)
options.SetPrefixLength(prefixLen)
response, err := vpcService.AddVPNGatewayConnectionPeerCIDR(options)
  • AddVpnGatewayConnectionPeerCidrOptions addVpnGatewayConnectionPeerCidrOptions = new AddVpnGatewayConnectionPeerCidrOptions.Builder()
  .vpnGatewayId(vpnGatewayId)
  .id(id)
  .cidrPrefix(prefixAddr)
  .prefixLength(prefixLength)
  .build();
Response<Void> response = service.addVpnGatewayConnectionPeerCidr(addVpnGatewayConnectionPeerCidrOptions).execute();
  • const params = {
  vpnGatewayId,
  id,
  cidrPrefix,
  prefixLength,
};

const response = await vpcService.addVpnGatewayConnectionPeerCidr(params);
  • response = service.add_vpn_gateway_connection_peer_cidr(
  vpn_gateway_id, id, prefix_address, prefix_length)

Response

Status Code

  • 204

    The CIDR was successfully set on the specified VPN gateway connection.

  • 400

    The specified CIDR was invalid.

  • 403

    The CIDR is not allowed to be set on the specified VPN gateway connection.

  • 404

    The specified VPN gateway connection could not be found.

No Sample Response

This method does not specify any sample responses.

List all VPN servers

This request lists all VPN servers.

GET /vpn_servers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • name
    string

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

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • sort
    string

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

    Allowable values: [created_at,name]

    Default: -created_at

    Example: name

  • curl -X GET "$vpc_api_endpoint/v1/vpn_servers?version=2024-04-16&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

Response Body

VPNServerCollection

Status Code

  • 200

    The VPN servers were retrieved successfully.

Example responses
  • {
  "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"
      }
    }
  ]
}

Create a VPN server

This request creates a new VPN server.

POST /vpn_servers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.create

  • is.security-group.security-group.operate

  • is.subnet.subnet.update

    Required for any subnet on which subnets specifies a new reserved IP on a subnet

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
VPNServerPrototype

The VPN server prototype

  • curl -X POST "$vpc_api_endpoint/v1/vpn_servers?version=2024-04-16&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

Response Body

VPNServer

Status Code

  • 201

    The VPN server was created successfully.

  • 400

    An invalid VPN server prototype object was provided.

  • 409

    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.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.delete

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server.delete

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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
)

Response

Status Code

  • 202

    The VPN server deletion request was accepted.

  • 403

    The VPN server is not allowed to be deleted.

  • 404

    A VPN server with the specified identifier could not be found.

  • 412

    The provided If-Match value does not match the current ETag value of the VPN server.

No Sample Response

This method does not specify any sample responses.

Retrieve a VPN server

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

GET /vpn_servers/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server.read

Request

Path Parameters

  • id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPNServer

Status Code

  • 200

    The VPN server was retrieved successfully.

  • 404

    A VPN server with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.update

  • is.subnet.subnet.update

    Required for any subnet on which subnets specifies a new reserved IP on a subnet

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPNServerPatch

The VPN server patch

  • curl -X PATCH "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id?version=2024-04-16&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

Response Body

VPNServer

Status Code

  • 200

    The VPN server was updated successfully.

  • 400

    An invalid VPN server patch was provided.

  • 403

    The VPN server is not allowed to be updated.

  • 404

    A VPC with the specified identifier could not be found.

  • 409

    The VPN server cannot be updated while it is being deleted, or the client address pool overlaps with an address prefix in this VPC.

  • 412

    The provided If-Match value does not match the current ETag value of the VPN server.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-configuration.read

Request

Path Parameters

  • id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

string

Status Code

  • 200

    The client configuration was retrieved successfully.

  • 404

    A VPN server with the specified identifier could not be found.

  • 406

    The media type specified in Accept request header is not acceptable. Only the media type text/plain is supported.

Example responses
  • 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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-client.list

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    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-16&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

Response Body

VPNServerClientCollection

Status Code

  • 200

    The VPN clients were retrieved successfully.

  • 404

    The specified VPN server could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.operate

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-client.delete

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN client identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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
)

Response

Status Code

  • 202

    The VPN client deletion request was accepted.

  • 403

    The VPN client is not allowed to be deleted.

  • 404

    A VPN client with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-client.read

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN client identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPNServerClient

Status Code

  • 200

    The VPN client was retrieved successfully.

  • 404

    A VPN client with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.operate

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-client.disconnect

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN client identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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
)

Response

Status Code

  • 202

    The VPN client disconnection request was accepted.

  • 403

    The VPN route is not allowed to be disconnected.

  • 404

    A VPN client with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-route.list

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    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-16&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

Response Body

VPNServerRouteCollection

Status Code

  • 200

    The VPN routes were retrieved successfully.

  • 404

    The specified VPN server could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-route.create

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
VPNServerRoutePrototype

The VPN route prototype object

  • curl -X POST   "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-16&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

Response Body

VPNServerRoute

Status Code

  • 201

    The VPN route was created successfully.

  • 400

    An invalid VPN route prototype object was provided.

  • 403

    The VPN route is not allowed to be created.

  • 404

    The specified VPN server could not be found.

  • 409

    The VPN route prototype object conflicts with another VPN route in the VPN server.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-route.delete

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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
)

Response

Status Code

  • 202

    The VPN route deletion request was accepted.

  • 403

    The VPN route is not allowed to be deleted.

  • 404

    A VPN route with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.read

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-route.read

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

VPNServerRoute

Status Code

  • 200

    The VPN route was retrieved successfully.

  • 404

    A VPN route with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.vpn-server.vpn-server.update

Auditing

Calling this method generates the following auditing event.

  • is.vpn-server.vpn-server-route.update

Request

Path Parameters

  • vpn_server_id
    Required*
    string

    The VPN server identifier

  • id
    Required*
    string

    The VPN route identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonVPNServerRoutePatch

The VPN route patch

  • curl -X PATCH   "$vpc_api_endpoint/v1/vpn_servers/$vpn_server_id/routes/$route_id?version=2024-04-16&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

Response Body

VPNServerRoute

Status Code

  • 200

    The VPN route was updated successfully.

  • 400

    An invalid VPN route patch was provided.

  • 403

    The VPN route is not allowed to be updated.

  • 404

    A VPN route with the specified identifier could not be found.

  • 409

    The VPN route cannot be updated while it is being deleted.

Example responses
  • {
  "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

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-profile.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

LoadBalancerProfileCollection

Status Code

  • 200

    The load balancer profiles were retrieved successfully

Example responses
  • {
  "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}

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-profile.read

Request

Path Parameters

  • name
    Required*
    string

    The load balancer profile name

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerProfile

Status Code

  • 200

    The load balancer profile was retrieved successfully

  • 404

    A load balancer profile with the specified name could not be found.

Example responses
  • {
  "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
  }
}

List all load balancers

This request lists all load balancers in the region.

GET /load_balancers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

LoadBalancerCollection

Status Code

  • 200

    The load balancers were retrieved successfully.

Example responses
  • {
  "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
}

Create a load balancer

This request creates and provisions a new load balancer.

POST /load_balancers

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

  • is.security-group.security-group.operate

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer.create

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerPrototype

The load balancer prototype object

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers?version=2024-04-16&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

Response Body

LoadBalancer

Status Code

  • 201

    The load balancer was created successfully.

  • 400

    An invalid load balancer prototype object was provided.

  • 409

    A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer.delete

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

  • 202

    The load balancer deletion request was accepted.

  • 404

    A load balancer with the specified identifier could not be found.

  • 409

    The load balancer cannot be deleted because it is in its current state, it is in use, or it is referenced by another resource

  • 412

    The provided If-Match value does not match the current ETag value of the load balancer.

No Sample Response

This method does not specify any sample responses.

Retrieve a load balancer

This request retrieves a single load balancer specified by the identifier in the URL path.

GET /load_balancers/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer.read

Request

Path Parameters

  • id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancer

Status Code

  • 200

    The load balancer was retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer.update

Request

Custom Headers

  • If-Match
    string

    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

  • id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerPatch

The load balancer patch

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id?version=2024-04-16&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

Response Body

LoadBalancer

Status Code

  • 200

    The load balancer was updated successfully.

  • 400

    An invalid load balancer patch was provided.

  • 404

    A load balancer with the specified identifier could not be found.

  • 409

    The load balancer cannot be updated in its current state.

  • 412

    The provided If-Match value does not match the current ETag value of the load balancer.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Request

Path Parameters

  • id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerStatistics

Status Code

  • 200

    The load balancer statistics were retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerListenerCollection

Status Code

  • 200

    The listeners of the load balancer were retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener.create

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerListenerPrototype

The load balancer listener prototype object

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners?version=2024-04-16&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

Response Body

LoadBalancerListener

Status Code

  • 201

    The listener was created successfully.

  • 400

    An invalid listener prototype object was provided.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener.delete

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The listener identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The listener deletion request was accepted.

  • 404

    A load balancer or listener with the specified identifier could not be found.

  • 409

    The listener is in use and cannot be deleted

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The listener identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerListener

Status Code

  • 200

    The listener was retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener.update

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The listener identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerListenerPatch

The load balancer listener patch

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id?version=2024-04-16&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

Response Body

LoadBalancerListener

Status Code

  • 200

    The listener update request was accepted.

  • 400

    An invalid listener patch was provided.

  • 404

    A listener with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Response Body

LoadBalancerListenerPolicyCollection

Status Code

  • 200

    The policies of the listener were retrieved successfully.

  • 404

    A load balancer or listener with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy.create

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerListenerPolicyPrototype

The listener policy prototype object

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies?version=2024-04-16&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

Response Body

LoadBalancerListenerPolicy

Status Code

  • 201

    The policy was created successfully.

  • 400

    An invalid listener policy prototype object was provided.

  • 404

    A load balancer or listener with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy.delete

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • id
    Required*
    string

    The policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The policy deletion request was accepted.

  • 404

    A load balancer or listener with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • id
    Required*
    string

    The policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerListenerPolicy

Status Code

  • 200

    The policy was retrieved successfully.

  • 404

    A load balancer or listener with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy.update

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • id
    Required*
    string

    The policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerListenerPolicyPatch

The listener policy patch

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id?version=2024-04-16&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

Response Body

LoadBalancerListenerPolicy

Status Code

  • 200

    The policy update request was accepted.

  • 400

    An invalid listener policy patch was provided.

  • 404

    A load balancer or listener with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy-rule.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • policy_id
    Required*
    string

    The policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Response Body

LoadBalancerListenerPolicyRuleCollection

Status Code

  • 200

    The rules of the policy were retrieved successfully.

  • 404

    A load balancer, listener, or policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy-rule.create

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • policy_id
    Required*
    string

    The policy identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerListenerPolicyRulePrototype

The listener policy rule prototype object

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules?version=2024-04-16&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

Response Body

LoadBalancerListenerPolicyRule

Status Code

  • 201

    The rule was created successfully.

  • 400

    An invalid rule prototype object was provided.

  • 404

    A load balancer, listener, or policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy-rule.delete

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • policy_id
    Required*
    string

    The policy identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The rule deletion request was accepted.

  • 404

    A load balancer, listener or policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy-rule.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • policy_id
    Required*
    string

    The policy identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerListenerPolicyRule

Status Code

  • 200

    The rule was retrieved successfully.

  • 404

    A load balancer, listener or policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-listener-policy-rule.update

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • listener_id
    Required*
    string

    The listener identifier

  • policy_id
    Required*
    string

    The policy identifier

  • id
    Required*
    string

    The rule identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerListenerPolicyRulePatch

The listener policy rule patch.

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/listeners/$listener_id/policies/$policy_id/rules/$rule_id?version=2024-04-16&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

Response Body

LoadBalancerListenerPolicyRule

Status Code

  • 200

    The rule update request was accepted.

  • 400

    An invalid rule patch was provided.

  • 404

    A load balancer, listener or policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all pools of a load balancer

This request lists all pools of a load balancer.

GET /load_balancers/{load_balancer_id}/pools

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerPoolCollection

Status Code

  • 200

    The pools of the load balancer were retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool.create

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerPoolPrototype

The load balancer pool prototype object.

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools?version=2024-04-16&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

Response Body

LoadBalancerPool

Status Code

  • 201

    The pool was created successfully.

  • 400

    An invalid pool prototype object was provided.

  • 404

    A load balancer with the specified identifier could not be found.

  • 409

    A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool.delete

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The pool deletion request was accepted.

  • 404

    A load balancer or pool with the specified identifier could not be found.

  • 409

    The pool is currently the default pool for one or more listeners, or the pool is the target for a listener policy.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerPool

Status Code

  • 200

    The pool was retrieved successfully.

  • 404

    A load balancer with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool.update

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerPoolPatch

The load balancer pool patch

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id?version=2024-04-16&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

Response Body

LoadBalancerPool

Status Code

  • 200

    The pool update request was accepted.

  • 400

    An invalid pool patch was provided.

  • 404

    A pool with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool-member.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    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-16&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

Response Body

LoadBalancerPoolMemberCollection

Status Code

  • 200

    The members of the load balancer pool were retrieved successfully.

  • 404

    A load balancer or pool with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool-member.create

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerPoolMemberPrototype

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.

  • curl -X POST "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members?version=2024-04-16&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

Response Body

LoadBalancerPoolMember

Status Code

  • 201

    The member was created successfully.

  • 400

    An invalid member prototype object was provided.

  • 404

    A load balancer or pool with the specified identifier could not be found.

  • 409

    The load balancer pool member prototype object conflicts with another load balancer pool member in the VPC.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
LoadBalancerPoolMemberCollectionPrototype

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.

  • curl -X PUT "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members?version=2024-04-16&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

Response Body

LoadBalancerPoolMemberCollection

Status Code

  • 202

    The update request was accepted.

  • 400

    An invalid member prototype object was provided.

  • 404

    A load balancer or pool with the specified identifier could not be found.

  • 409

    A load balancer pool member prototype object conflicts with other load balancer pool members in the VPC.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool-member.delete

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

  • id
    Required*
    string

    The member identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 202

    The member deletion request was accepted.

  • 404

    A load balancer, pool or member with the specified identifier could not be found.

  • 409

    The load balancer pool member is managed by an instance group.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.view

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool-member.read

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

  • id
    Required*
    string

    The member identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

LoadBalancerPoolMember

Status Code

  • 200

    The member was retrieved successfully.

  • 404

    A member with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing event.

  • is.load-balancer.load-balancer-pool-member.update

Request

Path Parameters

  • load_balancer_id
    Required*
    string

    The load balancer identifier

  • pool_id
    Required*
    string

    The pool identifier

  • id
    Required*
    string

    The member identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonLoadBalancerPoolMemberPatch

The load balancer pool member patch

  • curl -X PATCH "$vpc_api_endpoint/v1/load_balancers/$load_balancer_id/pools/$pool_id/members/$member_id?version=2024-04-16&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

Response Body

LoadBalancerPoolMember

Status Code

  • 200

    The member update request was accepted.

  • 400

    An invalid pool member patch was provided.

  • 404

    A pool member with the specified identifier could not be found.

  • 409

    The load balancer pool member patch conflicts with another load balancer pool member in the VPC.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.list

  • is.endpoint-gateway.endpoint-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.endpoint-gateway.endpoint-gateway.list

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • name
    string

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

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • lifecycle_state
    string[]

    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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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

  • allow_dns_resolution_binding
    boolean

    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-16&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

Response Body

EndpointGatewayCollection

Status Code

  • 200

    The endpoint gateways were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.create

  • is.vpc.vpc.operate

  • is.subnet.subnet.update

    Required for any subnet on which ips specifies one or more new reserved IPs

  • is.subnet.subnet.operate

    Required for any subnet on which ips specifies one or more existing reserved IPs

  • is.security-group.security-group.operate

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

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
EndpointGatewayPrototype

The endpoint gateway prototype

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/endpoint_gateways?version=2024-04-16&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

Response Body

EndpointGateway

Status Code

  • 201

    The endpoint gateway was created successfully.

  • 400

    An invalid endpoint gateway prototype object was provided.

  • 409

    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.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

    Required for any subnet that has reserved IPs bound to this endpoint gateway. (Otherwise, those reserved IPs will be omitted.)

Auditing

Calling this method generates the following auditing event, depending on any listed conditions.

  • is.subnet.reserved-ip.read

    Generated for each reserved IP in the list

Request

Path Parameters

  • endpoint_gateway_id
    Required*
    string

    The endpoint gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • sort
    string

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

    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-16&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

Response Body

ReservedIPCollectionEndpointGatewayContext

Status Code

  • 200

    The bound reserved IPs were retrieved successfully.

  • 404

    An endpoint gateway with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.operate

  • is.subnet.subnet.operate

Auditing

Calling this method generates the following auditing events, depending on any listed conditions.

  • is.endpoint-gateway.endpoint-gateway.detach

  • is.subnet.reserved-ip.detach

  • is.subnet.reserved-ip.delete

    Generated when the reserved IP has auto_delete set to true

Request

Path Parameters

  • endpoint_gateway_id
    Required*
    string

    The endpoint gateway identifier

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The reserved IP was successfully unbound from the endpoint gateway.

  • 400

    The reserved IP could not be unbound from the endpoint gateway.

  • 404

    The specified endpoint gateway or reserved IP could not be found, or the reserved IP is not bound to the endpoint gateway

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.subnet.subnet.read

Auditing

Calling this method generates the following auditing event.

  • is.subnet.reserved-ip.read

Request

Path Parameters

  • endpoint_gateway_id
    Required*
    string

    The endpoint gateway identifier

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIP

Status Code

  • 200

    The bound reserved IP was retrieved successfully.

  • 404

    The bound reserved IP with the specified identifier could not be found

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.operate

  • is.subnet.subnet.operate

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

  • endpoint_gateway_id
    Required*
    string

    The endpoint gateway identifier

  • id
    Required*
    string

    The reserved IP identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

ReservedIP

Status Code

  • 201

    The reserved IP was successfully bound to the endpoint gateway.

  • 400

    The specified reserved IP could not be bound to the endpoint gateway.

  • 404

    An endpoint gateway with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.delete

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 which auto_delete is true

  • 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

  • id
    Required*
    string

    The endpoint gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The endpoint gateway was deleted successfully.

  • 404

    An endpoint gateway with the specified identifier could not be found.

  • 409

    The endpoint gateway is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve an endpoint gateway

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

GET /endpoint_gateways/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.endpoint-gateway.endpoint-gateway.read

Request

Path Parameters

  • id
    Required*
    string

    The endpoint gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

EndpointGateway

Status Code

  • 200

    The endpoint gateway was retrieved successfully.

  • 404

    An endpoint gateway with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.endpoint-gateway.endpoint-gateway.update

Auditing

Calling this method generates the following auditing event.

  • is.endpoint-gateway.endpoint-gateway.update

Request

Path Parameters

  • id
    Required*
    string

    The endpoint gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonEndpointGatewayPatch

The endpoint gateway patch

  • curl -X PATCH "$vpc_api_endpoint/v1/endpoint_gateways/$endpoint_gateway_id?version=2024-04-16&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

Response Body

EndpointGateway

Status Code

  • 200

    The endpoint gateway was updated successfully.

  • 400

    An invalid endpoint gateway patch was provided.

  • 404

    A VPC with the specified identifier could not be found.

  • 409

    The endpoint gateway patch object specified an allow_dns_resolution_binding value that conflicts with the dns.enable_hub value of the VPC this endpoint gateway resides in.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.flow-log-collector.flow-log-collector.read

Auditing

Calling this method generates the following auditing event.

  • is.flow-log-collector.flow-log-collector.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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_]+$

  • name
    string

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

  • vpc.id
    string

    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_]+$

  • vpc.crn
    string

    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

  • vpc.name
    string

    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

  • target.id
    string

    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_]+$

  • target.resource_type
    string

    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-16&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

Response Body

FlowLogCollectorCollection

Status Code

  • 200

    The flow log collectors were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.flow-log-collector.flow-log-collector.create

  • is.vpc.vpc.operate

    Required when target specifies a VPC

  • is.subnet.subnet.operate

    Required when target specifies a subnet

  • is.instance.instance.operate

    Required when target specifies an instance, instance network attachment or instance network interface

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 instance

  • is.instance.network-attachment.attach

    Generated when target specifies an instance network attachment

  • is.instance.network-interface.attach

    Generated when target specifies an instance network interface

  • is.subnet.subnet.attach

    Generated when target specifies a subnet

  • is.virtual-network-interface.virtual-network-interface.attach

    Generated when target specifies a virtual network interface

  • is.vpc.vpc.attach

    Generated when target specifies a VPC

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
FlowLogCollectorPrototype

The flow log collector prototype object

Examples:
View
  • curl -X POST "$vpc_api_endpoint/v1/flow_log_collectors?version=2024-04-16&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

Response Body

FlowLogCollector

Status Code

  • 201

    The flow log collector was created successfully.

  • 400

    An invalid flow log collector prototype object was provided.

  • 409

    The specified target is in use by another flow log collector.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.flow-log-collector.flow-log-collector.delete

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

  • id
    Required*
    string

    The flow log collector identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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)

Response

Status Code

  • 204

    The flow log collector was deleted successfully.

  • 404

    The specified flow log collector could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.flow-log-collector.flow-log-collector.read

Auditing

Calling this method generates the following auditing event.

  • is.flow-log-collector.flow-log-collector.read

Request

Path Parameters

  • id
    Required*
    string

    The flow log collector identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

FlowLogCollector

Status Code

  • 200

    The flow log collector was retrieved successfully.

  • 404

    The specified flow log collector could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.flow-log-collector.flow-log-collector.update

Auditing

Calling this method generates the following auditing event.

  • is.flow-log-collector.flow-log-collector.update

Request

Path Parameters

  • id
    Required*
    string

    The flow log collector identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonFlowLogCollectorPatch

The flow log collector patch

  • curl -X PATCH "$vpc_api_endpoint/v1/flow_log_collectors/$flow_log_collector_id?version=2024-04-16&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

Response Body

FlowLogCollector

Status Code

  • 200

    The flow log collector was updated successfully.

  • 400

    An invalid flow log collector patch was provided.

  • 404

    A flow log collector with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.private-path-service-gateway.read

  • is.private-path-service-gateway.private-path-service-gateway.list

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.private-path-service-gateway.read

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • resource_group.id
    string

    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-16&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

Response Body

PrivatePathServiceGatewayCollection

Status Code

  • 200

    The private path service gateways were retrieved successfully.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.private-path-service-gateway.create

  • is.vpc.vpc.operate

  • is.load-balancer.load-balancer.manage

Auditing

Calling this method generates the following auditing events.

  • is.private-path-service-gateway.private-path-service-gateway.create

  • is.private-path-service-gateway.load-balancer.attach

  • is.load-balancer.private-path-service-gateway.attach

Request

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
PrivatePathServiceGatewayPrototype

The private path service gateway prototype

  • curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways?version=2024-04-16&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

Response Body

PrivatePathServiceGateway

Status Code

  • 201

    The private path service gateway was created successfully.

  • 400

    An invalid private path service gateway prototype object was provided.

Example responses
  • {
  "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_gateways_count must be 0. This operation cannot be reversed.

DELETE /private_path_service_gateways/{id}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.private-path-service-gateway.delete

Auditing

Calling this method generates the following auditing events.

  • is.private-path-service-gateway.private-path-service-gateway.delete

  • is.load-balancer.load-balancer.manage

  • is.private-path-service-gateway.load-balancer.detach

  • is.load-balancer.private-path-service-gateway.detach

Request

Path Parameters

  • id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

PrivatePathServiceGateway

Status Code

  • 202

    The private path service gateway deletion request was accepted.

  • 404

    A private path service gateway with the specified identifier could not be found.

  • 409

    The private path service gateway is in use and cannot be deleted.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.private-path-service-gateway.read

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.private-path-service-gateway.read

Request

Path Parameters

  • id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    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-16&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

Response Body

PrivatePathServiceGateway

Status Code

  • 200

    The private path service gateway was retrieved successfully.

  • 404

    A private path service gateway with the specified identifier could not be found.

Example responses
  • {
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.private-path-service-gateway.update

  • is.load-balancer.load-balancer.operate

    Required when load_balancer is updated.

  • is.private-path-service-gateway.private-path-service-gateway.publish

    Required when published is set to true.

  • is.private-path-service-gateway.private-path-service-gateway.unpublish

    Required when published is set to false.

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 to true.

  • is.private-path-service-gateway.private-path-service-gateway.unpublish

    Generated when published is set to false.

  • 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 to false.

  • is.private-path-service-gateway.endpoint-gateway-binding.deny

    Generated when published is set to false.

Request

Path Parameters

  • id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonPrivatePathServiceGatewayPatch

The private path service gateway patch.

  • curl -X PATCH   "$vpc_api_endpoint/v1/private_path_service_gateways/$private_path_service_gateway_id?version=2024-04-16&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

Response Body

PrivatePathServiceGateway

Status Code

  • 200

    The private path service gateway was updated successfully.

  • 400

    An invalid private path service gateway patch was provided.

  • 404

    A private path service gateway with the specified identifier could not be found.

Example responses
  • {
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.list

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.account-policy.list

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • account.id
    string

    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

Response Body

PrivatePathServiceGatewayAccountPolicyCollection

Status Code

  • 200

    The account policies were retrieved successfully.

  • 404

    The specified private path service gateway could not be found.

Example responses
  • {
  "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",
      "updated_at": "2022-01-08T11:23:14Z"
    }
  ],
  "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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.manage

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.account-policy.create

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
PrivatePathServiceGatewayAccountPolicyPrototype

The account policy prototype

Response

Response Body

PrivatePathServiceGatewayAccountPolicy

Status Code

  • 201

    The account policy for the private path service gateway was created successfully.

  • 400

    An invalid account policy prototype object was provided.

  • 404

    The specified private path service gateway could not be found.

Example responses
  • {
  "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",
  "updated_at": "2022-01-08T11:23:14Z"
}

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.manage

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.account-policy.delete

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The account policy identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Response

Status Code

  • 204

    The account policy was deleted successfully.

  • 404

    An account policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.read

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.account-policy.read

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The account policy identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Response

Response Body

PrivatePathServiceGatewayAccountPolicy

Status Code

  • 200

    The account policy was retrieved successfully.

  • 404

    An account policy with the specified identifier could not be found.

Example responses
  • {
  "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",
  "updated_at": "2022-01-08T11:23:14Z"
}

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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.manage

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.account-policy.update

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The account policy identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
application/merge-patch+jsonPrivatePathServiceGatewayAccountPolicyPatch

The account policy patch

Response

Response Body

PrivatePathServiceGatewayAccountPolicy

Status Code

  • 200

    The account policy was updated successfully.

  • 400

    An invalid account policy patch was provided.

  • 404

    An account policy with the specified identifier could not be found.

Example responses
  • {
  "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",
  "updated_at": "2022-01-08T11:23:14Z"
}

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.endpoint-gateway-binding.list

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.endpoint-gateway-binding.list

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

  • start
    string

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

  • limit
    int32

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 100

    Default: 50

  • status
    string

    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]+)*$

  • account.id
    string

    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

Response Body

PrivatePathServiceGatewayEndpointGatewayBindingCollection

Status Code

  • 200

    The endpoint gateway bindings were retrieved successfully.

  • 404

    The specified private path service gateway could not be found.

Example responses
  • {
  "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",
      "updated_at": "2022-01-08T11:23:14Z"
    }
  ],
  "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}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.endpoint-gateway-binding.read

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.endpoint-gateway-binding.read

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The endpoint gateway binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Response

Response Body

PrivatePathServiceGatewayEndpointGatewayBinding

Status Code

  • 200

    The endpoint gateway binding was retrieved successfully.

  • 404

    An endpoint gateway binding with the specified identifier could not be found.

Example responses
  • {
  "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",
  "updated_at": "2022-01-08T11:23:14Z"
}

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.endpoint-gateway-binding.manage

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.endpoint-gateway-binding.deny

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The endpoint gateway binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

PrivatePathServiceGatewayEndpointGatewayBindingDenyOptions

Options to control the deny operation.

  • curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/$id/deny?version=2024-04-16&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)

Response

Status Code

  • 200

    The private path service gateway endpoint gateway binding was denied

  • 400

    An invalid options object was provided.

  • 404

    An endpoint gateway binding with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.endpoint-gateway-binding.manage

Auditing

Calling this method generates the following auditing event.

  • is.private-path-service-gateway.endpoint-gateway-binding.permit

Request

Path Parameters

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

  • id
    Required*
    string

    The endpoint gateway binding identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

PrivatePathServiceGatewayEndpointGatewayBindingPermitOptions

Options to control the permit operation.

  • curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/endpoint_gateway_bindings/$id/permit?version=2024-04-16&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)

Response

Status Code

  • 200

    The endpoint gateway binding for the private path service gateway was permitted

  • 400

    An invalid options object was provided.

  • 404

    An endpoint gateway binding with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

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

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

  • is.private-path-service-gateway.account-policy.manage

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

  • private_path_service_gateway_id
    Required*
    string

    The private path service gateway identifier

Query Parameters

  • version
    Required*
    string

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-04-09 and 2024-04-16.

    Possible values: length = 10, Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • generation
    Required*
    int32

    The infrastructure generation. For the API behavior documented here, specify 2.

    Allowable values: [2]

Request Body

Required*
PrivatePathServiceGatewayRevokeAccountOptions

Options to control the revoke operation.

  • curl -X POST "$vpc_api_endpoint/v1/private_path_service_gateways/{private_path_service_gateway_id}/revoke_account?version=2024-04-16&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)

Response

Status Code

  • 200

    The account's access to the private path service gateway was revoked successfully.

  • 400

    An invalid options object was provided.

  • 404

    A private path service gateway with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.