Virtual Private Cloud API | IBM Cloud API Docs

Introduction

Last updated: 2024-11-19

With the IBM Cloud® Virtual Private Cloud (VPC) API, you can programmatically provision and manage resources that are part of the IBM VPC Infrastructure as a Service (IaaS) across compute, storage, and networking. For more information on the IBM Cloud® Virtual Private Cloud and VPC resources, see Getting started with Virtual Private Cloud (VPC).

SDKs

SDKs for Java, Node, Python, and Go are available for this API. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries.

To learn about using IBM Cloud® Virtual Private Cloud, see:

This documentation describes the Go SDK version 0.61.0. This SDK uses Semantic Versioning, and as such, there may be backward-incompatible changes for any new 0.y.z version. For information about the latest Go SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Java SDK version 0.21.0. This SDK uses Semantic Versioning, and as such, there may be backward-incompatible changes for any new 0.y.z version. For information about the latest Java SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Node SDK version 0.22.0. This SDK uses Semantic Versioning, and as such, there may be backward-incompatible changes for any new 0.y.z version. For information about the latest Node SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Python SDK version 0.24.1. This SDK uses Semantic Versioning, and as such, there may be backward-incompatible changes for any new 0.y.z version. For information about the latest Python SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

The code examples on this tab use the client library that is provided for Go.

Installation:

go get github.com/IBM/vpc-go-sdk@v0.61.0

For more information, view the project on GitHub: https://github.com/IBM/vpc-go-sdk/. See also Using the SDK.

The code examples on this tab use the client library that is provided for Java.

Maven example:

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>vpc</artifactId>
    <version>0.21.0</version>
</dependency>

Gradle example:

compile 'com.ibm.cloud:vpc:0.21.0'

For more information, view the project on GitHub: https://github.com/IBM/vpc-java-sdk/. See also Using the SDK.

The code examples on this tab use the client library that is provided for Node.

Installation:

npm install ibm-vpc

For more information, view the project on GitHub: https://github.com/IBM/vpc-node-sdk/. See also Using the SDK.

The code examples on this tab use the client library that is provided for Python.

Installation:

pip install --upgrade "ibm-vpc>=0.24.1"

For more information, view the project on GitHub: https://github.com/IBM/vpc-python-sdk/. See also the Python client library for IBM Cloud VPC Services https://pypi.org/project/ibm-vpc/ and Using the SDK.

Endpoint URLs

The IBM Cloud VPC API is available in the following IBM Cloud® regions:

Location	Region	Endpoint (service URL)
Washington DC	us-east	`https://us-east.iaas.cloud.ibm.com/v1`
Dallas	us-south	`https://us-south.iaas.cloud.ibm.com/v1`
Toronto	ca-tor	`https://ca-tor.iaas.cloud.ibm.com/v1`
São Paulo	br-sao	`https://br-sao.iaas.cloud.ibm.com/v1`
Frankfurt	eu-de	`https://eu-de.iaas.cloud.ibm.com/v1`
Madrid	eu-es	`https://eu-es.iaas.cloud.ibm.com/v1`
London	eu-gb	`https://eu-gb.iaas.cloud.ibm.com/v1`
Sydney	au-syd	`https://au-syd.iaas.cloud.ibm.com/v1`
Osaka	jp-osa	`https://jp-osa.iaas.cloud.ibm.com/v1`
Tokyo	jp-tok	`https://jp-tok.iaas.cloud.ibm.com/v1`

To call the API, select the service URL that corresponds to the region of your choice and add a method path to form the complete request URL. For example, to list all images available in the us-south region, make a GET request to https://us-south.iaas.cloud.ibm.com/v1/images.

To change the SDK service URL, reinstantiate the service instance with a different region-specific URL. For more information, see Using the SDK.

Example request to call the us-south service URL:

curl -H "Authorization: Bearer {token}" -X {http_method} "https://us-south.iaas.cloud.ibm.com/v1{path}"

Replace {token}, {http_method}, and {path} in this example with the values for your particular request.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

authenticator := &core.IamAuthenticator{
  ApiKey: "{api_key}",
}

options := &vpcv1.VpcV1Options{
  Authenticator: authenticator,
  URL:  "https://eu-gb.iaas.cloud.ibm.com/v1",
}

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

Authenticator authenticator = new IamAuthenticator("{api_key}");
Vpc service = new Vpc("{version}", Vpc.DEFAULT_SERVICE_NAME, authenticator);
setServiceUrl("https://eu-gb.iaas.cloud.ibm.com/v1");
Copy to clipboard

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

const service = {
  authenticator: new IamAuthenticator({
    apikey: '{api_key}'
  }),
  serviceUrl: 'https://eu-gb.iaas.cloud.ibm.com/v1'
};
const vpcService = new VpcV1(service);
Copy to clipboard

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

from ibm_vpc import VpcV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('apikey')
service = VpcV1(authenticator=authenticator)
service.set_service_url('https://eu-gb.iaas.cloud.ibm.com/v1')
Copy to clipboard

For more information, see Using the SDK.

Authentication

The IBM Cloud VPC API uses Identity and Access Management (IAM) to authenticate requests. To call each API method, you must be assigned a role that includes the required IAM actions. Each method has an Authorization section that lists the required actions and, if applicable, the conditions under which each action is required. Check your access on the IBM Cloud console by navigating to Users > User > Access.

For more information about IAM actions and how they map to roles, see Assigning access to account management services and Managing IAM access for VPC Infrastructure Services.

Learn about obtaining an IAM token for an authenticated user or service ID in the IAM Identity Services API. If you first create an API key, you can use it to generate an IAM token.

To use the API, add a valid IAM token to the HTTP Authorization request header. For example, -H 'Authorization: Bearer {token}'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically, by constructing an IAM authenticator instance and supplying your IAM API key.
Externally, in configuration options that are then used by the SDK to construct an IAM authenticator at run time.

Provide external configuration options by either:

Storing the configuration options in environment variables. When you initialize the service client, the SDK constructs the authenticator by reading the configuration properties directly from the environment variables.
Saving the configuration options in a file. When you initialize the service client, the SDK constructs the authenticator by reading the configuration properties from the file specified by the IBM_CREDENTIALS_FILE environment variable.

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section in the IBM Cloud SDK Common documentation.

Outside of development and testing, never hard-code secrets (such as IAM API keys) into a client application.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={api_key}'
Copy to clipboard

To use the API, replace {token} with the token obtained above from IAM, replace {http_method} with an HTTP method such as POST, and replace {url} with a request URL such as https://us-south.iaas.cloud.ibm.com/v1/keys:

curl -H "Authorization: Bearer {token}" -X {http_method} "{url}"

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key:

import {
  "github.com/IBM/go-sdk-core/v5/core"
  "github.com/IBM/vpc-go-sdk/vpcv1"
}
// Create an IAM authenticator.
authenticator := &core.IamAuthenticator{
  ApiKey: "{api_key}",
}
// Construct an "options" struct for creating the service client.
options := &vpcv1.VpcV1Options{
  Authenticator: authenticator,                            // required
  URL:           "https://us-east.iaas.cloud.ibm.com/v1",  // optional
}
// Construct the service client.
vpcService, err := vpcv1.NewVpcV1(options)
if err != nil {
  panic(err)
}
Copy to clipboard

Service operations can now be invoked using the vpcService variable.

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}
Copy to clipboard

Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig() initializes the client with the environment variables, using them for subsequent authentication.

vpcService, err := vpcv1.NewVpcV1UsingExternalConfig()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig() initializes with the defined credential file, using it for subsequent authentication.

vpcService, err := vpcv1.NewVpcV1UsingExternalConfig()

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key.

import com.ibm.cloud.is.vpc.v1.Vpc;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;
// Create an IAM authenticator.
Authenticator authenticator = new IamAuthenticator.Builder()
  .apikey("{api_key}")
  .build();
// Construct the service client.
Vpc service = new Vpc(Vpc.DEFAULT_SERVICE_NAME, authenticator);
// Set our custom service URL (optional).
service.setServiceUrl("https://us-east.iaas.cloud.ibm.com/v1");
Copy to clipboard

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}
Copy to clipboard

Construct the service client using external configuration. Vpc.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

import com.ibm.cloud.is.vpc.v1.Vpc;
Vpc service = Vpc.newInstance();
Copy to clipboard

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. Vpc.newInstance() initializes with the defined credential file, using it for subsequent authentication.

import com.ibm.cloud.is.vpc.v1.Vpc;
Vpc service = Vpc.newInstance();
Copy to clipboard

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const { IamAuthenticator } = require('vpc-node-sdk/auth');

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
  apikey: '{api_key}',
});

// Construct the service client.
const vpcService = new VpcV1({
  authenticator,                                       // required
  serviceUrl: 'https://us-east.iaas.cloud.ibm.com/v1', // optional
});
Copy to clipboard

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}
Copy to clipboard

Construct the service client using external configuration. VpcV1.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const vpcService = VpcV1.newInstance();
Copy to clipboard

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. VpcV1.newInstance() initializes with the defined credential file, using it for subsequent authentication.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const vpcService = VpcV1.newInstance();
Copy to clipboard

Setting client options programmatically

Construct the service client, where {api_key} is your hardcoded IAM API key

from ibm_vpc import VpcV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create an IAM authenticator.
authenticator = IAMAuthenticator('{api_key}')
# Construct the service client.
service = VpcV1(authenticator=authenticator)
# Set custom service URL (optional)
service.set_service_url('https://us-east.iaas.cloud.ibm.com/v1')
Copy to clipboard

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}
Copy to clipboard

Construct the service client using external configuration. VpcV1.new_instance() initializes the client with the environment variables, using them for subsequent authentication.

from ibm_vpc import VpcV1
service = VpcV1.new_instance()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. VpcV1.new_instance() initializes with the defined credential file, using it for subsequent authentication.

from ibm_vpc import VpcV1
service = VpcV1.new_instance()

Authorization

Access to VPC infrastructure resources is managed through IAM. IAM provides the ability to manage resources through resource groups and access management tags. For more information, see Managing IAM access for VPC Infrastructure Services.

Auditing

Monitor API activity within your account by using the IBM Cloud Activity Tracker service. Each time you make an API call, one or more events are generated that you can track and audit from within Activity Tracker. Specific auditing event types are listed for each individual method. For more information about how to track VPC activity, see Activity Tracker events.

Error handling

This API uses standard HTTP response codes to indicate the outcome of a request. A 4xx-series response indicates a failure that the client must resolve. A 5xx-series response indicates a service failure.

HTTP Error Code	Description	Recovery
`400`	Bad Request	The input parameters in the request body are either incomplete, malformed, or too large. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try submitting the request again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to perform the requested operation. Either you do not have valid access through IAM access policies or your request is denied due to the context-based restriction policy. If this error persists, contact the account owner to check your permissions.
`404`	Not Found	The requested resource could not be found but may be available in the future.
`405`	Method Not Allowed	The requested resource does not support the request method.
`406`	Not Acceptable	The resource the client requested is not available in a format allowed by the `Accept` header supplied by the client.
`408`	Request Timeout	The connection to the server timed out. Wait a few minutes, and try submitting the request again.
`409`	Conflict	The request cannot be completed because of a conflict between the request and the current state of the resource.
`412`	Precondition Failed	The client specified one or more preconditions in its headers, and the server cannot meet those preconditions.
`426`	Upgrade Required	The server refuses to perform the request using the current protocol but might perform the request after the client upgrades to a different protocol.
`500`	Internal Server Error	The request cannot be processed because the client encountered an unexpected condition on the server. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support.
`501`	Not Implemented	The server either does not recognize the request method, or it lacks the ability to fulfill the request.
`502`	Bad Gateway	The server was acting as a gateway or proxy and received an invalid response from the upstream server.
`503`	Service Unavailable	The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition could also be due to an unplanned outage of a service that is needed to process the request. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support.
`504`	Gateway Timeout	The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
`505`	HTTP Version Not Supported	The server does not support the HTTP protocol version that is used in the request.

Error handling example:

import "github.com/IBM/vpc-go-sdk/vpcv1"

// Instantiate a service
vpcService, vpcServiceErr := vpcv1.NewVpcV1(options)

// Check for errors
if vpcServiceErr != nil {
  panic(vpcServiceErr)
}

// Call a method
listVpcsOptions := &vpcv1.ListVpcsOptions{}
  vpcs, _, err := vpcService.ListVpcs(listVpcsOptions)

// Check for errors
if err != nil {
  panic(err)
}
Copy to clipboard

Error handling example:

try {
  // Invoke an operation
  Response<Resource> response = service.getResource(options).execute();


  // Process response...


} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
  // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
  // Base class for all exceptions caused by error responses from the service
  System.out.println("Service returned status code "
    + e.getStatusCode() + ": " + e.getMessage());
  System.out.println("Detailed error info:\n" + e.getDebuggingInfo().toString());
}
Copy to clipboard

Error handling example:

try {
    const response = await vpcService.getResource();
    // ...handle successful response...
} catch (err) {
    // ...handle error response...
    console.log("Error status code: " + err.status + " (" + err.statusText + ")");
    console.log("Error message:     " + err.message);
}
Copy to clipboard

Example of error handling:

from ibm_cloud_sdk_core import ApiException

try:
    vpcs = service.list_vpcs().get_result()['vpcs']
except ApiException as e:
    print("List VPC failed with status code " + str(e.code) + ": " + e.message)
Copy to clipboard

Versioning

This reference documents API behavior for any date value in the version parameter between 2024-11-19 and today's date. To view the reference for an older version of the API, select it from the Version list.

Requests to the VPC API require a major version as the first segment of the request path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD.

The VPC API supports a continuous series of version dates from 2019-01-01 to today's date (in UTC).

Most changes to the VPC API are designed to be compatible with existing clients and are made available to clients that specify any supported version date. For example, support for new paths, new optional parameters, and additional properties in responses are considered backward compatible and, when possible, are made available without respect to the version date specified by a client.

By design, backward-incompatible changes, such as the removal or restructuring of existing properties or parameters, are made available only for clients that specify version dates on or after the feature became available.

To maximize the compatibility of your client with future API changes, follow the best practices for client development.

When you develop a new client, specify the current date (as of the time of development) as a fixed value for the version parameter, and keep that same fixed version date value when you test and ship your client. Do not specify a value for the version parameter that is dynamically computed based on the date your code is compiled or executed.

Features that require clients to specify a later version date are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions.

As a best practice, review the change log on a periodic basis. To use the latest features and maintain ongoing compatibility, update and test your client with a newer version date. As with new clients, specify the current date (as of the time you update your client code) as a fixed value for the version parameter.

Deprecation

A method, path, parameter, property or other feature will be marked as deprecated when usage is no longer recommended, such as when it's been rendered obsolete by new features. After a feature is deprecated, support for that feature may be removed for clients that specify new version dates.

Features that are no longer supported in new API versions are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions.

The oldest supported version date (currently 2019-01-01) may be moved forward in the future, necessitating clients to specify a newer version date and make any updates needed to work with that newer version.

Each SDK version uses a corresponding version of the API that it was developed and tested to be compatible with.

Example request to list regions in the 2024-11-19 version of the v1 API:

curl -X GET   "$vpc_api_endpoint/v1/regions?version=2024-11-19&generation=2"   -H "Authorization: Bearer $iam_token"

Property value expansion

Unless explicitly stated otherwise, relaxing constraints for a property's values is considered a backward-compatible change that is expected to occur to accommodate new features or products. Backward-compatible property value expansion supports the following:

For numeric properties: increasing maximum values or decreasing minimum values
For array properties: increasing maximum item counts or decreasing minimum item counts
For string properties: increasing maximum lengths or decreasing minimum lengths
For cron specification properties: increasing the scheduling frequency
For enumerations: expanding the set of enumerated values
For One of: adding choices to an existing One of selection

For example, the maximum value for the Share iops property in the specification reflects the current maximum IOPS that can be supported by the IBM Cloud VPC File Storage service. However, the value in the specification may be subsequently increased, even for existing API versions. Likewise, the values for enumerations, such as the Share access_control_mode, encryption, and replication_status properties may be subsequently expanded, even for existing API versions. Additionally, a set of One of choices, such as adding another choice for security group targets, may be expanded in the future for existing API versions.

To maximize the compatibility of your client with future API changes, follow the best practices for client development.

Concurrent update protection

To prevent multiple clients from unknowingly overwriting each other's updates, select API methods support entity-tags and conditional requests as specified in RFC 7232.

To make a conditional request, first issue a GET request on the resource to retrieve its up-to-date representation. The response will include an ETag header, whose value is a fingerprint of the resource's current client-configurable state. Next, verify that the method you want to perform (typically an update or a delete) is appropriate given the current state of the resource. For example, you may want to only delete a VPN server if its port property has a specific value. Finally, if the resource is still in the appropriate state, issue the API request, as usual, but make the request conditional by including an If-Match header with its value set to the ETag value from the earlier GET request.

Because the If-Match header was provided, the server will check that the resource's current ETag value (which reflects the client-configurable state) matches the value you provided in the If-Match header. If the two values match, the server can be certain the resource has not been updated in the interim, and request processing continues as usual. Otherwise, the resource was updated (by another client) between the time you issued the GET and the time you issued the conditional request, and the request will fail with 412 Precondition Failed. Because a resource may be updated by another client at any time, clients issuing conditional requests must be written to check for a 412 failure, and if encountered, restart the sequence by reissuing the original GET request.

Because 412 indicates that the resource has been updated, before reissuing the conditional request, the client must both retrieve the latest ETag value using GET and verify that the representation of the resource is still appropriate for the conditional request.

For additional safety, the VPC API requires that any PATCH request that includes an array property must also provide an If-Match header. For example, a PATCH /volumes/{id} request that includes the user_tags array property will fail with 400 Bad Request if the If-Match header is not provided. In contrast, a PATCH /volumes/{id} request to modify just the name string property need not provide an If-Match header (since no array is present). However, if the If-Match header is provided, the server will check its value and will return 412 Precondition Failed if the value is not current.

The ETag and If-Match headers must be used only on methods that have explicit documentation that those headers are supported. Other related headers described in RFC 7232, such as If-None-Match and If-Modified-Since, are not supported at this time.

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, omit the maturity query parameter. For information on making beta requests, see the Beta VPC API reference.

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.

The default and maximum limits might vary by operation. To specify a different page size, use the limit query parameter.

For a request that uses pagination, the response includes additional properties:

The first.href property links to the first page of resources
The next.href property links to the next page of resources (included for all pages except for the last page)

Use query parameters to page through your available resources and retrieve a subset of objects. To retrieve the first page of results, make the request without specifying a start query parameter. If the results cannot fit on the first page, the response will include a next property, whose value can then be specified as the start parameter when making the next page request. Each page of results is based on the resources that exist at the time of each paginated request, and therefore may include resources that did not exist when the first request was made. The last page of results will not include a next property.

When you're retrieving a subset of objects:

You must add the version and generation query parameters to the href value before you make the request
You may use the value of first.href to retrieve the first page of resources in the requested sort order and with the requested filters
You may use the value of next.href to retrieve the next page of resources in the requested sort order and with the requested filters
You may not change the requested filters across page retrievals
You may not add a sort query parameter to the href value (sort order is set by the first paginated list request)
You may modify the limit in the href value to limit the number of resources to return, per page, in a paginated list operation
You may not change the path segments of the request (that is, anything before the ? in the href value)

List the first five keys: .../keys?limit=5

List the first five keys on the next page: .../keys?limit=5&start=9d5a91a3e2cbd233b5a5b33436855ed1

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
Copy to clipboard

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

next := "r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
	listVpcsOptions := &vpcv1.ListVpcsOptions{
		Limit: core.Int64Ptr(1),
		Start: &next,
	}
	vpcs, _, err := vpcService.ListVpcs(listVpcsOptions)

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
Copy to clipboard

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

ListVpcsOptions listVpcsOptions = new ListVpcsOptions.Builder()
.start("r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217")
.limit(Long.valueOf("10"))
.build();
Response<VPCCollection> response = service.listVpcs(listVpcsOptions).execute();
VPCCollection vpcCollectionResult = response.getResult();
Copy to clipboard

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
Copy to clipboard

Copy the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 to the clipboard, and use that value in your next call to fetch page 2:

      const listVpcsResult = vpcService.listVpcs({
          start: 'r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217',
          limit: 10,
        });
Copy to clipboard

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
Copy to clipboard

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

    next = response.get_result()['next']
try:
    response = service.list_vpcs(start="r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217", limit=1).get_result()['vpcs']
except ApiException as e:
    print("List VPC failed with status code " + str(e.code) + ": " + e.message)
Copy to clipboard

Response model properties

Certain properties are included in API responses for all customer-created VPC resources. The created_at value is a timestamp that matches when the resource became visible through calls to the IBM Cloud VPC API.

Generation

To use the IBM Cloud VPC infrastructure, send the generation=2 query parameter with every API request.

Example: Create a VPC

POST /v1/vpcs?generation=2

Variables

Consider storing frequently used values (such as the API service URL, authorization token, API version, and other resource identifiers) in variables.

The following topics contain information on setting variables:

Example of storing the us-south service URL in a variable:

vpc_api_endpoint=https://us-south.iaas.cloud.ibm.com

Resources

The VPC API is structured around resources of various types, such as block storage volumes (called "volumes" in the API), and virtual server instances (called "instances" in the API). Each resource consists of a set of properties and supports a set of operations, such as updating some of its property values, or deleting the resource. Certain complex resources also have child resources. For example, the instance resource has one or more volume attachment child resources, with each volume attachment associating the instance with a volume it uses. As with other resources, child resources also have a set of properties and a set of operations, which can be performed on the child resource. Child resources can also have their own child resources.

There is a hierarchical relationship between a resource and its child resources, which is reflected in VPC's API path hierarchy. For example, the API path to retrieve a volume attachment is GET /instances/{instance_id}/volume_attachments/{id}, reflecting that every volume attachment has an instance as its parent resource. This hierarchy is also evident in their lifecycles: deleting an instance will delete all of its child resources, including all of its volume attachments.

Resources that appear in the first segment of the API path hierarchy, such as /instances in the previous example, are sometimes referred to as top-level resources. By convention, top-level resources in the VPC API have crn properties that provide the resource's global Cloud Resource Name (CRN). These CRNs enable top-level resources to be integrated with other IBM Cloud services, such as IAM, billing, and global tagging. For example, because volume attachments are a child resource and do not have their own CRNs, it is not possible to create an IAM policy for a specific volume attachment. Instead, the IAM policies for the parent instance's CRN control access to its volume attachments.

In many situations, the distinction between a top-level resource and a child resource is not important, and the term "resource" is often used to refer to either type of resource.

Resource modeling

Each resource type in the VPC API is represented by a handful of data models, which tailor the resource's properties to the operation being performed:

Prototype model: Used in the request body when creating a resource with POST.
Base model: Returned in the response body when retrieving a resource with GET. This model is also returned in the response body from many other operations, such as when creating a resource.
Patch model: Used in the request body when updating a resource with PATCH.
Identity model: Used when identifying a resource in a request body.
Reference model: Used when identifying a resource in a response body.

Models go hand in hand with objects. An object is an instantiation of a model. For example, POST /instances requires a request body that adheres to the InstancePrototype model, and that request body is an instance prototype object. The response body from POST /instances adheres to the Instance model, and that response body is an instance object. Likewise, the PATCH /instances/{id} request body is an InstancePatch object, and the response body is an Instance object.

In the VPC API, resources are often associated with other resources. When creating an association with a resource, that resource's identity model is used. For example, POST /instances/{id}/volume_attachments, which creates a new volume attachment, expects a VolumeAttachmentPrototype object. That object includes a volume property (VolumeIdentity model) that identifies the volume to attach. As a convenience, some resources have multiple ways to identify them, such as volume.crn, volume.id or volume.href in this scenario.

For an association to succeed, the caller's IAM policies must permit the caller to operate on the identified resource. Additionally, the identified resource must be in the caller's account unless a specific property documents an exception.

To ensure predictable behavior, mutable properties, such as a resource's mutable name, are never included in identity models.

When a resource is retrieved, its association with another resource is shown using that resource's reference model. Continuing the previous example, GET /instances/{instance_id}/volume_attachments/{id} returns a VolumeAttachment object, which includes a volume property (VolumeReference model). In addition to including the identifiers that were present in the VolumeIdentity model (volume.crn, volume.id, and volume.href), it also includes its volume.name, and an optional volume.deleted property, which indicates that the resource no longer exists.

Many reference models also include a resource_type property, which is essential in polymorphic contexts. For example, the floating IP resource (FloatingIP model) includes a target property, which is a oneOf that can refer to a NetworkInterfaceReference or a PublicGatewayReference depending on the way the floating IP resource was created. Further, new types of floating IP targets might be introduced in the future. A client that calls GET /floating_ips/{id} can check the value of target.resource_type to determine if target refers to a network interface resource, a public gateway resource, or another resource type that was introduced after the client was developed.

The properties in a resource's identity and reference models are not subject to that resource's IAM policies. For example, although the volume property included in the response from GET /instances/{instance_id}/volume_attachments/{id} included identifying information about the volume, such as its name and id, the caller did not need an IAM policy to read the volume. This design facilitates adhering to least privilege, because the caller can understand the associations a resource has with other resources without having to be granted access to see the specifics of the associated resources. However, because of this design, it's important to never place sensitive information in a resource's name.

Resource names

VPC resource names adhere to a common regular expression that:

Forbids uppercase characters
Forbids trailing dashes
Reserves leading dashes for system use
Has a name length of 1 - 63 characters
Allows leading digits for system-owned resources (and, eventually, for all resources)
- On a request, the permitted regex is ^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$.
  
  Resources that do not yet allow leading digits use ^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$.
- On a response, the possible regex is ^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$.

Resource namespaces are per resource type and per account. For example, a volume and a server in the same availability zone (AZ) and account can both be named b, and two accounts can both contain a volume that is named b in the same AZ.

For a resource type within an account:

If the resource is scoped within a parent resource, names must be unique within that parent resource.
If the resource is scoped within a VPC, names must be unique within that VPC.
If the resource is regional (or smaller), names must be regionally unique.

If a resource's namespace can contain both customer-created and IBM-created resources, all IBM-created resources (such as IBM-provided images) begin with ibm-. Customers are unable to create resources with the prefix ibm-.

Resource names that begin with a hyphen (-) are reserved for system use and are sometimes used in place of user-defined names. For example, names included with references to deleted resources are prefixed with -deleted-.

If you don't name a resource during resource creation, the system automatically generates a resource name.

Deleted resources

In some responses, embedded resource references may refer to resources that have been deleted. This possibility is noted in contexts where it's expected. Rarely, references to deleted resources may also appear when the system cannot resolve a conflict between concurrent requests.

The presence of a deleted property can be used to determine that a reference is to a deleted resource. The deleted property contains an object with a more_info link to relevant documentation.

As shown in the example, references to deleted resources will have a name prefixed with -deleted- and suffixed with a value to ensure the resource remains unique within its namespace, even if its user-defined name has been reused. This name should not be parsed for information and may not contain any part of the original user-defined name.

Deleted resource reference example:

{
  "name": "-deleted-e1b7144d1645",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/b6b9395e-6a4d-4291-b824-e1b7144d1645",
  "crn": "crn:[...]",
  "deleted": {
    "more_info": "https://cloud.ibm.com/apidocs/vpc#deleted-resources"
  }
}
Copy to clipboard

Remote resources

In some responses, embedded resource references may refer to resources that are in another region, in another account, or in both another region and another account. If a given reference can be remote, the specification will include a remote property, which can contain account and region child properties, which identify the remote account and remote region for the resource, respectively.

The remote reference shown in the example shows a source image that is both in a different account, and in a region (us-south) that is different from the region being called (us-east). Because the resource has no representation in the region being called, the href for the resource refers to its native region (us-south.iaas.cloud.ibm.com). In contrast, because the remote.region has a representation in the region being called, the remote.region.href refers to the called region (us-east.iaas.cloud.ibm.com).

When authoring clients that operate on remote references, bear the following in mind:

The resource may have the same name as another local resource, which it may have no relationship to.
Mutable information, such as its name and whether it has been deleted, may not be current.
The resource cannot be directly accessed and may not be accessible at all. For example, attempting to retrieve the example resource above using GET /v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8 results in 404 because the resource is in another account. However, if the resource had been in the same account, but still in a different region, the GET method would result in a 301 Moved Permanently, allowing clients that support redirects to retrieve the resource from its native region.

As discussed in Resources, reference models are not subject to the resource's IAM policies. Therefore, even if the IAM policy that allowed the remote reference to be established is revoked, any remote references that were previously established may continue to have their name updated. Because of this design, it's important to never place sensitive information in a resource's name.

Remote resource reference example:

{
  "crn": "crn:v1:bluemix:public:is:us-south:a/02828f9c8fd74b73859d371a406af2a1::image:72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "id": "72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "name": "my-image",
  "remote": {
    "account": {
      "id": "02828f9c8fd74b73859d371a406af2a1",
      "resource_type": "account"
    },
    "region": {
       "href": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south",
       "name": "us-south",
       "resource_type": "region"
    }
  }
}
Copy to clipboard

Resource suspension

Individual resources that violate IBM Cloud® terms of service will be suspended. Potential resources that can be suspended include virtual server instances, VPN gateways and VPN servers.

While a resource is suspended, it cannot be used, modified, or deleted. For example, suspended virtual server instances are powered off, and their configuration may not be changed. Connections to VPN gateways and servers are disabled.

Resources that have been suspended will have a lifecycle_state of suspended and a lifecycle_reasons[].code of resource_suspended_by_provider. For information about restoring a suspended resource, see Resource suspension in VPC Getting Started.

API best practices

To minimize bugs caused by changes, follow these best practices when making an API requests:

When processing values for properties that have been expanded, such as for numeric, array, string, and enumeration values, check for and log unknown values. Optionally halt processing and surface the error, or bypass the resource on which the unexpected property value was encountered.
Catch and log any 4xx or 5xx HTTP status code along with the included trace property
Follow HTTP redirect rules for any 3xx HTTP status code.
Use only the resources and properties that are needed for your client to function.
Do not send any extraneous input in a request.
Specify a fixed value for the API version parameter
Avoid depending on any behavior that is not explicitly documented.

Change log

Important changes to the API, such as additions, updates, and deprecations, are documented in the change log.

Features that require clients to specify a later version date are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions. See Versioning for more information.

SDK changes are based on API changes. When a new API version is available, the SDK reflects changes in the API.

Beta Virtual Private Cloud API

This request lists 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

(vpc *VpcV1) ListVpcs(listVpcsOptions *ListVpcsOptions) (result *VPCCollection, response *core.DetailedResponse, err error)

(vpc *VpcV1) ListVpcsWithContext(ctx context.Context, listVpcsOptions *ListVpcsOptions) (result *VPCCollection, response *core.DetailedResponse, err error)

list_vpcs(
        self,
        *,
        start: Optional[str] = None,
        limit: Optional[int] = None,
        resource_group_id: Optional[str] = None,
        classic_access: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<VPCCollection> listVpcs(ListVpcsOptions listVpcsOptions)
Copy to clipboard

listVpcs(params)

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

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

(vpc *VpcV1) CreateVPC(createVPCOptions *CreateVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

(vpc *VpcV1) CreateVPCWithContext(ctx context.Context, createVPCOptions *CreateVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

create_vpc(
        self,
        *,
        address_prefix_management: Optional[str] = None,
        classic_access: Optional[bool] = None,
        dns: Optional['VPCDNSPrototype'] = None,
        name: Optional[str] = None,
        resource_group: Optional['ResourceGroupIdentity'] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<VPC> createVpc(CreateVpcOptions createVpcOptions)
Copy to clipboard

createVpc(params)

Authorization

To call this method, you must be 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

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.

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.

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.

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.

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}

(vpc *VpcV1) DeleteVPC(deleteVPCOptions *DeleteVPCOptions) (response *core.DetailedResponse, err error)

(vpc *VpcV1) DeleteVPCWithContext(ctx context.Context, deleteVPCOptions *DeleteVPCOptions) (response *core.DetailedResponse, err error)

delete_vpc(
        self,
        id: str,
        *,
        if_match: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<Void> deleteVpc(DeleteVpcOptions deleteVpcOptions)
Copy to clipboard

deleteVpc(params)

Authorization

To call this method, you must be 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

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

GET /vpcs/{id}

(vpc *VpcV1) GetVPC(getVPCOptions *GetVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

(vpc *VpcV1) GetVPCWithContext(ctx context.Context, getVPCOptions *GetVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

get_vpc(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<VPC> getVpc(GetVpcOptions getVpcOptions)
Copy to clipboard

getVpc(params)

Authorization

To call this method, you must be 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

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}

(vpc *VpcV1) UpdateVPC(updateVPCOptions *UpdateVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

(vpc *VpcV1) UpdateVPCWithContext(ctx context.Context, updateVPCOptions *UpdateVPCOptions) (result *VPC, response *core.DetailedResponse, err error)

update_vpc(
        self,
        id: str,
        vpc_patch: 'VPCPatch',
        *,
        if_match: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<VPC> updateVpc(UpdateVpcOptions updateVpcOptions)
Copy to clipboard

updateVpc(params)

Authorization

To call this method, you must be 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

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

(vpc *VpcV1) GetVPCDefaultNetworkACL(getVPCDefaultNetworkACLOptions *GetVPCDefaultNetworkACLOptions) (result *DefaultNetworkACL, response *core.DetailedResponse, err error)

(vpc *VpcV1) GetVPCDefaultNetworkACLWithContext(ctx context.Context, getVPCDefaultNetworkACLOptions *GetVPCDefaultNetworkACLOptions) (result *DefaultNetworkACL, response *core.DetailedResponse, err error)

get_vpc_default_network_acl(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<DefaultNetworkACL> getVpcDefaultNetworkAcl(GetVpcDefaultNetworkAclOptions getVpcDefaultNetworkAclOptions)
Copy to clipboard

getVpcDefaultNetworkAcl(params)

Authorization

To call this method, you must be 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

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

(vpc *VpcV1) GetVPCDefaultRoutingTable(getVPCDefaultRoutingTableOptions *GetVPCDefaultRoutingTableOptions) (result *DefaultRoutingTable, response *core.DetailedResponse, err error)

(vpc *VpcV1) GetVPCDefaultRoutingTableWithContext(ctx context.Context, getVPCDefaultRoutingTableOptions *GetVPCDefaultRoutingTableOptions) (result *DefaultRoutingTable, response *core.DetailedResponse, err error)

get_vpc_default_routing_table(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<DefaultRoutingTable> getVpcDefaultRoutingTable(GetVpcDefaultRoutingTableOptions getVpcDefaultRoutingTableOptions)
Copy to clipboard

getVpcDefaultRoutingTable(params)

Authorization

To call this method, you must be 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

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

(vpc *VpcV1) GetVPCDefaultSecurityGroup(getVPCDefaultSecurityGroupOptions *GetVPCDefaultSecurityGroupOptions) (result *DefaultSecurityGroup, response *core.DetailedResponse, err error)

(vpc *VpcV1) GetVPCDefaultSecurityGroupWithContext(ctx context.Context, getVPCDefaultSecurityGroupOptions *GetVPCDefaultSecurityGroupOptions) (result *DefaultSecurityGroup, response *core.DetailedResponse, err error)

get_vpc_default_security_group(
        self,
        id: str,
        **kwargs,
    ) -> DetailedResponse

ServiceCall<DefaultSecurityGroup> getVpcDefaultSecurityGroup(GetVpcDefaultSecurityGroupOptions getVpcDefaultSecurityGroupOptions)
Copy to clipboard

getVpcDefaultSecurityGroup(params)

Authorization

To call this method, you must be 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

This request lists address pool prefixes for a VPC.

GET /vpcs/{vpc_id}/address_prefixes

(vpc *VpcV1) ListVPCAddressPrefixes(listVPCAddressPrefixesOptions *ListVPCAddressPrefixesOptions) (result *AddressPrefixCollection, response *core.DetailedResponse, err error)

(vpc *VpcV1) ListVPCAddressPrefixesWithContext(ctx context.Context, listVPCAddressPrefixesOptions *ListVPCAddressPrefixesOptions) (result *AddressPrefixCollection, response *core.DetailedResponse, err error)

list_vpc_address_prefixes(
        self,
        vpc_id: str,
        *,
        start: Optional[str] = None,
        limit: Optional[int] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<AddressPrefixCollection> listVpcAddressPrefixes(ListVpcAddressPrefixesOptions listVpcAddressPrefixesOptions)
Copy to clipboard

listVpcAddressPrefixes(params)

Authorization

To call this method, you must be 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

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

(vpc *VpcV1) CreateVPCAddressPrefix(createVPCAddressPrefixOptions *CreateVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

(vpc *VpcV1) CreateVPCAddressPrefixWithContext(ctx context.Context, createVPCAddressPrefixOptions *CreateVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

create_vpc_address_prefix(
        self,
        vpc_id: str,
        cidr: str,
        zone: 'ZoneIdentity',
        *,
        is_default: Optional[bool] = None,
        name: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<AddressPrefix> createVpcAddressPrefix(CreateVpcAddressPrefixOptions createVpcAddressPrefixOptions)
Copy to clipboard

createVpcAddressPrefix(params)

Authorization

To call this method, you must be 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

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}

(vpc *VpcV1) DeleteVPCAddressPrefix(deleteVPCAddressPrefixOptions *DeleteVPCAddressPrefixOptions) (response *core.DetailedResponse, err error)

(vpc *VpcV1) DeleteVPCAddressPrefixWithContext(ctx context.Context, deleteVPCAddressPrefixOptions *DeleteVPCAddressPrefixOptions) (response *core.DetailedResponse, err error)

delete_vpc_address_prefix(
        self,
        vpc_id: str,
        id: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<Void> deleteVpcAddressPrefix(DeleteVpcAddressPrefixOptions deleteVpcAddressPrefixOptions)
Copy to clipboard

deleteVpcAddressPrefix(params)

Authorization

To call this method, you must be 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

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

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

(vpc *VpcV1) GetVPCAddressPrefix(getVPCAddressPrefixOptions *GetVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

(vpc *VpcV1) GetVPCAddressPrefixWithContext(ctx context.Context, getVPCAddressPrefixOptions *GetVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

get_vpc_address_prefix(
        self,
        vpc_id: str,
        id: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<AddressPrefix> getVpcAddressPrefix(GetVpcAddressPrefixOptions getVpcAddressPrefixOptions)
Copy to clipboard

getVpcAddressPrefix(params)

Authorization

To call this method, you must be 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

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}

(vpc *VpcV1) UpdateVPCAddressPrefix(updateVPCAddressPrefixOptions *UpdateVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

(vpc *VpcV1) UpdateVPCAddressPrefixWithContext(ctx context.Context, updateVPCAddressPrefixOptions *UpdateVPCAddressPrefixOptions) (result *AddressPrefix, response *core.DetailedResponse, err error)

update_vpc_address_prefix(
        self,
        vpc_id: str,
        id: str,
        address_prefix_patch: 'AddressPrefixPatch',
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

ServiceCall<AddressPrefix> updateVpcAddressPrefix(UpdateVpcAddressPrefixOptions updateVpcAddressPrefixOptions)
Copy to clipboard

updateVpcAddressPrefix(params)

Authorization

To call this method, you must be 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

This request lists 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.