Virtual Private Cloud Metadata API

Introduction 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 VPChttps://cloud.ibm.com/docs/vpc?topic=vpc-getting-started. 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 references for using the client libraries. To learn about using IBM Cloud® Virtual Private Cloud, see: - Getting started with IBM Cloud VPChttps://cloud.ibm.com/docs/vpc?topic=vpc-getting-started - Setting up your API and CLI environmenthttps://cloud.ibm.com/docs/vpc?topic=vpc-set-up-environment&interface=api - Creating VPC resources with CLI and APIhttps://cloud.ibm.com/docs/vpc?topic=vpc-creating-vpc-resources-with-cli-and-api&interface=api This documentation describes the Go SDKhttps://github.com/IBM/vpc-go-sdk/. For information about the latest Go SDK, see Releaseshttps://github.com/IBM/vpc-go-sdk/releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. This documentation describes the Java SDKhttps://github.com/IBM/vpc-java-sdk. For information about the latest Java SDK, see Releaseshttps://github.com/IBM/vpc-java-sdk/releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. This documentation describes the Node SDKhttps://github.com/IBM/vpc-node-sdk. For information about the latest Node SDK, see Releaseshttps://github.com/IBM/vpc-node-sdk/releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. This documentation describes the Python SDKhttps://github.com/IBM/vpc-python-sdk. For information about the latest Python SDK, see Releaseshttps://github.com/IBM/vpc-python-sdk/releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-go-sdk/https://github.com/IBM/vpc-go-sdk/. See also Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-java-sdk/https://github.com/IBM/vpc-java-sdk/. See also Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-node-sdk/https://github.com/IBM/vpc-node-sdk/. See also Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-python-sdk/https://github.com/IBM/vpc-python-sdk/. See also the Python client library for IBM Cloud VPC Services https://pypi.org/project/ibm-vpc/https://pypi.org/project/ibm-vpc/ and Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Endpoint URLs The IBM Cloud VPC API is available in the following IBM Cloud® regions: | Location | Region | Public endpoint service URL | Private endpoint service URL | |--------------------------|------------|------------------------------------------|--------------------------------------------------| | Australia Sydney | au-syd | https://au-syd.iaas.cloud.ibm.com/v1 | https://au-syd.private.iaas.cloud.ibm.com/v1 | | Brazil São Paulo | br-sao | https://br-sao.iaas.cloud.ibm.com/v1 | https://br-sao.private.iaas.cloud.ibm.com/v1 | | Canada Montreal | ca-mon | https://ca-mon.iaas.cloud.ibm.com/v1 | https://ca-mon.private.iaas.cloud.ibm.com/v1 | | Canada Toronto | ca-tor | https://ca-tor.iaas.cloud.ibm.com/v1 | https://ca-tor.private.iaas.cloud.ibm.com/v1 | | Germany Frankfurt | eu-de | https://eu-de.iaas.cloud.ibm.com/v1 | https://eu-de.private.iaas.cloud.ibm.com/v1 | | Spain Madrid | eu-es | https://eu-es.iaas.cloud.ibm.com/v1 | https://eu-es.private.iaas.cloud.ibm.com/v1 | | United Kingdom London | eu-gb | https://eu-gb.iaas.cloud.ibm.com/v1 | https://eu-gb.private.iaas.cloud.ibm.com/v1 | | India Chennai | in-che | https://in-che.iaas.cloud.ibm.com/v1 | https://in-che.private.iaas.cloud.ibm.com/v1 | | India Mumbai | in-mum | https://in-mum.iaas.cloud.ibm.com/v1 | https://in-mum.private.iaas.cloud.ibm.com/v1 | | Japan Osaka | jp-osa | https://jp-osa.iaas.cloud.ibm.com/v1 | https://jp-osa.private.iaas.cloud.ibm.com/v1 | | Japan Tokyo | jp-tok | https://jp-tok.iaas.cloud.ibm.com/v1 | https://jp-tok.private.iaas.cloud.ibm.com/v1 | | US East Washington DC | us-east | https://us-east.iaas.cloud.ibm.com/v1 | https://us-east.private.iaas.cloud.ibm.com/v1 | | US South Dallas | us-south | https://us-south.iaas.cloud.ibm.com/v1 | https://us-south.private.iaas.cloud.ibm.com/v1 | See also Locations for resource deploymenthttps://cloud.ibm.com/docs/overview?topic=overview-locations. 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 SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Example request to call the us-south service URL: sh curl -H "Authorization: Bearer {token}" -X {httpmethod} "https://us-south.iaas.cloud.ibm.com/v1{path}" Replace {token}, {httpmethod}, and {path} in this example with the values for your particular request. Default service URL: text https://us-south.iaas.cloud.ibm.com/v1 Example to change the service URL to the United Kingdom region: go authenticator := &core.IamAuthenticator{ ApiKey: "{apikey}", } // Get the service URL for the specified region serviceURL, := vpcv1.GetServiceURLForRegion"eu-gb" options := &vpcv1.VpcV1Options{ Authenticator: authenticator, URL: serviceURL, } For more information, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Default service URL: text https://us-south.iaas.cloud.ibm.com/v1 Example to change the service URL to the United Kingdom region: java Authenticator authenticator = new IamAuthenticator"{apikey}"; Vpc service = new VpcVpc.DEFAULTSERVICENAME, authenticator; service.setServiceUrlVpc.getServiceUrlForRegion"eu-gb"; For more information, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Default service URL: text https://us-south.iaas.cloud.ibm.com/v1 Example to change the service URL to the United Kingdom region: javascript const options = { authenticator: new IamAuthenticator{ apikey: '{apikey}' }, serviceUrl: VpcV1.getServiceUrlForRegion"eu-gb", }; const service = new VpcV1options; For more information, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Default service URL: text https://us-south.iaas.cloud.ibm.com/v1 Example to change the service URL to the United Kingdom region: python from ibmvpc import VpcV1 from ibmcloudsdkcore.authenticators import IAMAuthenticator authenticator = IAMAuthenticator'apikey' service = VpcV1authenticator=authenticator service.setserviceurlVpcV1.getserviceurlforregion"eu-gb" For more information, see Using the SDKhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdusing-the-sdk. Authentication The IBM Cloud VPC API uses Identity and Access Management IAMhttps://cloud.ibm.com/docs/account?topic=account-iamoverview 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 consolehttps://cloud.ibm.com/login by navigating to Usershttps://cloud.ibm.com/iam/users User Access. For more information about IAM actions and how they map to roles, see Assigning access to account management serviceshttps://cloud.ibm.com/docs/account?topic=account-account-services&interface=api and Managing IAM access for VPC Infrastructure Serviceshttps://cloud.ibm.com/docs/vpc?topic=vpc-iam-getting-started&interface=api. Learn about obtaining an IAM token for an authenticated user or service ID in the IAM Identity Services APIhttps://cloud.ibm.com/apidocs/iam-identity-token-api. If you first create an API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api, you can use it to generate an IAM tokenhttps://cloud.ibm.com/docs/account?topic=account-iamtokenfromapikey. To use the API, add a valid IAM token to the HTTP Authorization request header. For example, -H 'Authorization: Bearer {token}'. To retrieve your access token: sh curl -X POST \ "https://iam.cloud.ibm.com/identity/token" \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --data-urlencode 'granttype=urn:ibm:params:oauth:grant-type:apikey' \ --data-urlencode 'apikey={apikey}' To use the API, replace {token} in the following example request with the token obtained from IAM in the previous request. Also replace {httpmethod} 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: sh curl -H "Authorization: Bearer {token}" -X {httpmethod} "{url}" When you use the SDK, configure an IAM authenticator with the IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. 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 IBMCREDENTIALSFILE 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 Commonhttps://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.mdauthentication documentation. Outside of development and testing, never hard-code secrets such as IAM API keys into a client application. Setting client options programmatically Construct the service client programmatically, where {apikey} is your hardcoded IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api: go import { "github.com/IBM/go-sdk-core/v5/core" "github.com/IBM/vpc-go-sdk/vpcv1" } // Create an IAM authenticator. authenticator := &core.IamAuthenticator{ ApiKey: "{apikey}", } // 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.NewVpcV1options if err = nil { panicerr } 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 {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh export VPCURL={serviceurl} export VPCAUTHTYPE=iam export VPCAPIKEY={apikey} Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig initializes the client with the environment variables, using them for subsequent authentication. go vpcService, err := vpcv1.NewVpcV1UsingExternalConfig Setting client options through a credentials file Store credentials in a file such as my-credentials.env, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh VPCURL={serviceurl} VPCAUTHTYPE=iam VPCAPIKEY={apikey} Export the name of the file with an environment variable, where {credentialfilepath} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env". sh export IBMCREDENTIALSFILE={credentialfilepath} Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig initializes with the defined credential file, using it for subsequent authentication. go vpcService, err := vpcv1.NewVpcV1UsingExternalConfig Setting client options programmatically Construct the service client programmatically, where {apikey} is your hardcoded IAM API key. java 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"{apikey}" .build; // Construct the service client. Vpc service = new VpcVpc.DEFAULTSERVICENAME, authenticator; // Set our custom service URL optional. service.setServiceUrl"https://us-east.iaas.cloud.ibm.com/v1"; Setting client options through environment variables Export environment variables to implement service client options, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh export VPCURL={serviceurl} export VPCAUTHTYPE=iam export VPCAPIKEY={apikey} Construct the service client using external configuration. Vpc.newInstance initializes the client with the environment variables, using them for subsequent authentication. java import com.ibm.cloud.is.vpc.v1.Vpc; Vpc service = Vpc.newInstance; Setting client options through a credentials file Store credentials in a file such as my-credentials.env, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh VPCURL={serviceurl} VPCAUTHTYPE=iam VPCAPIKEY={apikey} Export the name of the file with an environment variable, where {credentialfilepath} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env". sh export IBMCREDENTIALSFILE={credentialfilepath} Construct the service client using external configuration. Vpc.newInstance initializes with the defined credential file, using it for subsequent authentication. java import com.ibm.cloud.is.vpc.v1.Vpc; Vpc service = Vpc.newInstance; Setting client options programmatically Construct the service client programmatically, where {apikey} is your hardcoded IAM API key. javascript const VpcV1 = require'vpc-node-sdk/vpc/v1'; const { IamAuthenticator } = require'vpc-node-sdk/auth'; // Create an IAM authenticator. const authenticator = new IamAuthenticator{ apikey: '{apikey}', }; // Construct the service client. const vpcService = new VpcV1{ authenticator, // required serviceUrl: 'https://us-east.iaas.cloud.ibm.com/v1', // optional }; Setting client options through environment variables Export environment variables to implement service client options, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh export VPCURL={serviceurl} export VPCAUTHTYPE=iam export VPCAPIKEY={apikey} Construct the service client using external configuration. VpcV1.newInstance initializes the client with the environment variables, using them for subsequent authentication. javascript const VpcV1 = require'vpc-node-sdk/vpc/v1'; const vpcService = VpcV1.newInstance; Setting client options through a credentials file Store credentials in a file such as my-credentials.env, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh VPCURL={serviceurl} VPCAUTHTYPE=iam VPCAPIKEY={apikey} Export the name of the file with an environment variable, where {credentialfilepath} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env". sh export IBMCREDENTIALSFILE={credentialfilepath} Construct the service client using external configuration. VpcV1.newInstance initializes with the defined credential file, using it for subsequent authentication. javascript const VpcV1 = require'vpc-node-sdk/vpc/v1'; const vpcService = VpcV1.newInstance; Setting client options programmatically Construct the service client, where {apikey} is your hardcoded IAM API key python from ibmvpc import VpcV1 from ibmcloudsdkcore.authenticators import IAMAuthenticator Create an IAM authenticator. authenticator = IAMAuthenticator'{apikey}' Construct the service client. service = VpcV1authenticator=authenticator Set custom service URL optional service.setserviceurl'https://us-east.iaas.cloud.ibm.com/v1' Setting client options through environment variables Export environment variables to implement service client options, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh export VPCURL={serviceurl} export VPCAUTHTYPE=iam export VPCAPIKEY={apikey} Construct the service client using external configuration. VpcV1.newinstance initializes the client with the environment variables, using them for subsequent authentication. python from ibmvpc import VpcV1 service = VpcV1.newinstance Setting client options through a credentials file Store credentials in a file such as my-credentials.env, where {serviceurl} is an endpoint URL for the service and {apikey} is an IAM API keyhttps://cloud.ibm.com/docs/account?topic=account-userapikey&interface=apicreateuserkey-api. sh VPCURL={serviceurl} VPCAUTHTYPE=iam VPCAPIKEY={apikey} Export the name of the file with an environment variable, where {credentialfilepath} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env". sh export IBMCREDENTIALSFILE={credentialfilepath} Construct the service client using external configuration. VpcV1.newinstance initializes with the defined credential file, using it for subsequent authentication. python from ibmvpc import VpcV1 service = VpcV1.newinstance Authorization Access to VPC infrastructure resources is managed through IAMhttps://cloud.ibm.com/docs/account?topic=account-iamoverview. IAM provides the ability to manage resources through resource groupshttps://cloud.ibm.com/docs/vpc?topic=vpc-iam-getting-started&interface=apiiam-resource-groups and access management tagshttps://cloud.ibm.com/docs/vpc?topic=vpc-iam-getting-started&interface=apiiam-access-management-tags. For more information, see Managing IAM access for VPC Infrastructure Serviceshttps://cloud.ibm.com/docs/vpc?topic=vpc-iam-getting-started. Auditing IBM Cloud services, such as IBM Cloud VPC, generate activity tracking events. Activity tracking events report on activities that change the state of resources in IBM Cloud and also report on certain activities that do not change any state, such as attempts to access and update resources. You can use the events to investigate abnormal activity and critical actions and to comply with regulatory audit requirements. Monitor API activity within your account by using IBM Cloud Activity Tracker Event Routing, a platform service, to route auditing events to destinations of your choice. Configure targets and routes that define where activity tracking events are sent. Each time you make an API call, one or more events are generated that you can track and audit. Specific event types are listed for each method that generates auditing events. For methods that don't list any events, no events are generated. For more information, see About IBM Cloud Activity Tracker Event Routinghttps://cloud.ibm.com/docs/atracker?topic=atracker-about and Activity tracking events for IBM Cloud VPChttps://cloud.ibm.com/docs/vpc?topic=vpc-atevents&interface=ui. You can also use IBM Cloud Logs to visualize and alert on events that are generated in your account and routed by IBM Cloud Activity Tracker Event Routing to an IBM Cloud Logs instance. For more information, see Getting started with IBM Cloud Logshttps://cloud.ibm.com/docs/cloud-logs?topic=cloud-logs-getting-started. 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 policyhttps://cloud.ibm.com/docs/vpc?topic=vpc-cbr. 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. | If the server is unable to perform any part of the requested operation, the entire operation will fail, resulting in no observable change to any of the resources. For example, if a PATCH request is made to change two properties, but the caller is not authorized to change one of the properties, the request will fail with 403 Unauthorized, and the resource will be unchanged. Similarly, if a GET /volumes request is made to retrieve all the caller's volumes in the region, but one of the volumes is using a beta feature that cannot be expressed through the GA API schema, the entire request will fail, resulting in no volumes being returned. Because the 500 Internal Server Error and 408 Request Timeout HTTP status codes may be generated by entities between your client and the server such as a reverse proxy, it is possible that the server successfully processed your client's request, but that your client still received 500 or 408 from one of these entities. Therefore, when processing those status codes in response to a DELETE, PATCH, POST, or PUT request, you must not assume the request failed. Error handling example: go import "github.com/IBM/vpc-go-sdk/vpcv1" // Instantiate a service vpcService, vpcServiceErr := vpcv1.NewVpcV1options // Check for errors if vpcServiceErr = nil { panicvpcServiceErr } // Call a method listVpcsOptions := &vpcv1.ListVpcsOptions{} vpcs, , err := vpcService.ListVpcslistVpcsOptions // Check for errors if err = nil { panicerr } Error handling example: java try { // Invoke an operation Response