Introduction

The IBM Cloud™ Virtual Private Cloud (VPC) API is a RESTful API that lets you manage your VPC lifecycle and resources. Use the VPC API to provision instances with high network performance and fast port speeds.

This API is for use with generation 2 compute resource. Generation 2 resources aren't compatible with generation 1 resources. If you want to migrate your API scripts from generation 1 to generation 2, see API application migration considerations.

Familiarize yourself with VPC functionality described in About Virtual Private Cloud. See also the following topics:

Learn about setting up and managing a VPC in the following tutorials:

Authentication

The IBM Cloud VPC API uses Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

Authorization

Access management to VPC infrastructure resources is done through resource groups and IAM. The service VPC Infrastructure contains various resource types that can be controlled. Learn more about the required permissions for VPC resources.

API endpoint

The endpoint is based on the region of the service and follows the convention https://<region>.iaas.cloud.ibm.com.

Available endpoints by region:

Region name Region Endpoint
US South (Dallas) us-south https://us-south.iaas.cloud.ibm.com
Washington DC us-east https://us-east.iaas.cloud.ibm.com

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™ Virtual Private Cloud API.

Versioning

All API requests require a major version in the path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD. For example:

GET /v1/regions?version=2019-10-08

Any date-based version, up to the current date, is supported. Start development of new applications with the current date as a fixed value. Don't dynamically use the current date as the version for a production application. Instead, use a fixed date-based version that has been tested with your application. Periodically check the API change log for API changes. Update and test your application with new version dates to maintain ongoing compatibility.

For more information, see Versioning in the IBM Cloud Platform API Implementation Handbook.

API changes

API improvements and fixes are documented in the API change log, along with guidance on code updates required to use a new date-based version. By design, new features with backward-incompatible changes apply only to version dates on and after the feature's release. Changes that apply to older versions of the API are designed to maintain compatibility with existing applications and code.

Best practices

To minimize bugs caused by changes, follow these best practices when you call the API:

  • 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
  • Consume only the resources and properties needed for your application to function
  • Avoid depending on any behavior that is not explicitly documented

Generation

To use the IBM Cloud VPC infrastructure, send the generation=2 query parameter with every API request. For example, to create a VPC, run the following API call:

POST /v1/vpcs?generation=2

Variables

Consider storing frequently-used values in a variable. Values you might want to save include the API endpoint, authorization token, API version, and other resource identifiers.

Example: To store the endpoint in a variable, run this command:

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

To verify that the variable was saved, run echo $api_endpoint and be sure the response is not empty.

See the following topics for additional examples on setting variables:

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response indicates some sort of failure, and a 500 type response usually indicates an internal server error.

HTTP error code Description Disposition
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. 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 again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, and try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
501 Not Implemented The server either does not recognize the request method, or it lacks the ability to fulfil the request. Usually this implies future availability, such as a new feature of a web-service API.
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 is a temporary state, such as when a server is overloaded or down for scheduled maintenance.
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 used in the request.

Pagination

Some API requests can return a large number of results. Optionally include limit or start parameters in an API request to page through your available resources and retrieve a subset of objects.

Parameter Description
limit Limits the number of objects to return, 1 to 100.

The default limit (typically 100) depends on the specific API call. If limit is omitted, the system returns up to 100 objects.

Example: List the first 5 keys: .../keys?limit=5
start Returns the next page of results.

If the response does not contain a link to the next page of results, you have reached the end.

Example: Start on the 6th page: .../keys?limit=5&start=5

Methods

List all floating IPs

This request retrieves all floating IPs in the region. Floating IPs allow inbound and outbound traffic from the Internet to an instance.

GET /floating_ips
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

  • curl -X GET \
    "$rias_endpoint/v1/floating_ips?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The floating IPs were retrieved successfully.

Example responses
  • {
      "floating_ips": [
        {
          "address": "192.0.2.2",
          "created_at": "2019-01-28T12:08:05Z",
          "crn": "crn:[...]",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/4dd1852a-3373-46c0-9240-f9c7f0d0c1a3",
          "id": "4dd1852a-3373-46c0-9240-f9c7f0d0c1a3",
          "name": "my-floating-ip-1",
          "status": "pending",
          "target": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/f2a2ab09-0c9e-4b2d-a1cf-7425d1c834b9/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a2",
            "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a2",
            "name": "my-network-interface-1",
            "primary_ipv4_address": "10.0.1.9",
            "subnet": {
              "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4",
              "id": "1dfeccef-3ad6-4760-8653-a202bc795db4",
              "name": "my-subnet-1"
            }
          },
          "zone": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
            "name": "us-south-1"
          }
        },
        {
          "address": "198.51.100.1",
          "created_at": "2019-01-29T12:08:05Z",
          "crn": "crn:[...]",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/64580c28-713a-4cda-9993-53bc6a529bb4",
          "id": "64580c28-713a-4cda-9993-53bc6a529bb4",
          "name": "my-floating-ip-2",
          "status": "pending",
          "target": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/f2a2ab09-0c9e-4b2d-a1cf-7425d1c834b9/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32",
            "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364",
            "name": "my-network-interface-1",
            "primary_ipv4_address": "10.0.1.9",
            "subnet": {
              "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4",
              "id": "1dfeccef-3ad6-4760-8653-a202bc795db4",
              "name": "my-subnet-1"
            }
          },
          "zone": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
            "name": "us-south-1"
          }
        }
      ]
    }

Reserve a floating IP

This request reserves a new floating IP.

POST /floating_ips
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The floating IP template

Example:
  • curl -X POST \
    "$rias_endpoint/v1/floating_ips?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "name": "my-floating-ip-1",
          "target": {
            "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847"
          }
        }'
Response

Status Code

  • The floating IP was reserved successfully.

  • An invalid floating IP template was provided.

  • The specified target is in use by another floating IP.

Example responses
  • {
      "address": "192.0.2.2",
      "created_at": "2019-01-28T12:08:05Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "name": "my-floating-ip-1",
      "status": "pending",
      "target": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32/network_interfaces/5a07e83d-c1f3-4df2-bcec-41b09c006847",
        "id": "5a07e83d-c1f3-4df2-bcec-41b09c006847",
        "name": "my-network-interface-1",
        "primary_ipv4_address": "10.0.1.9",
        "subnet": {
          "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4",
          "id": "1dfeccef-3ad6-4760-8653-a202bc795db4",
          "name": "my-subnet-1"
        }
      },
      "zone": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
        "name": "us-south-1"
      }
    }

Release the specified floating IP

This request disassociates (if associated) and releases a floating IP. This operation cannot be reversed. For this request to succeed, the floating IP must not be required by another resource, such as a public gateway.

DELETE /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/floating_ips/$floating_ip_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The floating IP was released successfully.

  • The specified floating IP could not be found.

  • The floating IP is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified floating IP

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

GET /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/floating_ips/$floating_ip_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The floating IP was retrieved successfully.

  • The specified floating IP could not be found.

Example responses
  • {
      "address": "192.0.2.2",
      "created_at": "2019-01-28T12:08:05Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "name": "my-floating-ip-1",
      "status": "pending",
      "target": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/f2a2ab09-0c9e-4b2d-a1cf-7425d1c834b9/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32",
        "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32",
        "name": "my-network-interface-1",
        "primary_ipv4_address": "10.0.1.9",
        "subnet": {
          "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4",
          "id": "1dfeccef-3ad6-4760-8653-a202bc795db4",
          "name": "my-subnet-1"
        }
      },
      "zone": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
        "name": "us-south-1"
      }
    }

Update the specified floating IP

This request updates a floating IP's name and/or target.

PATCH /floating_ips/{id}
Request

Path Parameters

  • The floating IP identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The floating IP patch

  • curl -X PATCH \
    "$rias_endpoint/v1/floating_ips/$floating_ip_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name":"my-floating-ip-1" }'
Response

Status Code

  • The floating IP was updated successfully.

  • The supplied floating IP patch was invalid.

  • A floating IP with the specified identifier could not be found.

  • The specified target is in use by another floating IP.

Example responses
  • {
      "address": "198.51.100.1",
      "created_at": "2019-1-28T04:05:48Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/floating_ips/ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "id": "ad0cded3-53a3-4d4a-9809-8c59b50d2b80",
      "name": "my-floating-ip-1",
      "status": "available",
      "target": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instances/c2297e47-5373-4d9c-8a4e-f41b259c41bf/network_interfaces/bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32",
        "id": "bd5f7dc3-93c7-4d3a-89b4-26c4cc364a32",
        "name": "my-network-interface-1",
        "primary_ipv4_address": "10.0.1.11",
        "subnet": {
          "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/1dfeccef-3ad6-4760-8653-a202bc795db4",
          "id": "1dfeccef-3ad6-4760-8653-a202bc795db4",
          "name": "my-subnet-1"
        }
      },
      "zone": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/regions/us-south/zones/us-south-1",
        "name": "us-south-1"
      }
    }

List all IKE policies

This request retrieves a paginated list of all IKE policies that belong to this account.

GET /ike_policies
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • curl -X GET \
    "$rias_endpoint/v1/ike_policies?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IKE policies were retrieved successfully.

Example responses
  • {
      "ike_policies": [
        {
          "authentication_algorithm": "md5",
          "created_at": "2018-12-13T19:27:58.95704Z",
          "dh_group": 2,
          "encryption_algorithm": "aes256",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d",
          "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d",
          "ike_version": 1,
          "key_lifetime": 28800,
          "name": "my-ike-policy-0",
          "negotiation_mode": "main",
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          }
        },
        {
          "authentication_algorithm": "md5",
          "created_at": "2018-12-13T19:26:24.475125Z",
          "dh_group": 2,
          "encryption_algorithm": "aes256",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148",
          "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148",
          "ike_version": 1,
          "key_lifetime": 28800,
          "name": "my-ike-policy-1",
          "negotiation_mode": "main",
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          }
        }
      ]
    }

Create an IKE policy

This request creates a new IKE policy.

POST /ike_policies
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The IKE policy template.

  • curl -X POST \
    "$rias_endpoint/v1/ike_policies?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "authentication_algorithm": "md5",
          "dh_group": 2,
          "encryption_algorithm": "aes256",
          "ike_version": 1,
          "key_lifetime": 28800,
          "name": "my-ike-policy-1",
          "resource_group": {
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          }
        }'
Response

Status Code

  • The IKE policy was created successfully.

  • An invalid IKE policy template was provided.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:26:24.475125Z",
      "dh_group": 2,
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "ike_version": 1,
      "key_lifetime": 28800,
      "name": "my-ike-policy-1",
      "negotiation_mode": "main",
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      }
    }

Delete an IKE policy

This request deletes an IKE policy. This operation cannot be reversed.

DELETE /ike_policies/{id}
Request

Path Parameters

  • The IKE policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/ike_policies/$ike_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IKE policy was deleted successfully.

  • An IKE policy with the specified identifier could not be found.

  • The IKE policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified IKE policy

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

GET /ike_policies/{id}
Request

Path Parameters

  • The IKE policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/ike_policies/$ike_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IKE policy was retrieved successfully.

  • An IKE policy with the specified identifier could not be found.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:26:24.475125Z",
      "dh_group": 2,
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "ike_version": 1,
      "key_lifetime": 28800,
      "name": "my-ike-policy-1",
      "negotiation_mode": "main",
      "resource_group": {
        "href": "https://resource-manager.stage1.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      }
    }

Update an IKE policy

This request updates the properties of an existing IKE policy.

PATCH /ike_policies/{id}
Request

Path Parameters

  • The IKE policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The IKE policy patch.

  • curl -X PATCH \
    "$rias_endpoint/v1/ike_policies/$ike_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name": "my-new-ike-policy" }'
Response

Status Code

  • The IKE policy was updated successfully.

  • An invalid IKE policy patch was provided.

  • An IKE policy with the specified identifier could not be found.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:26:24.475125Z",
      "dh_group": 2,
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "id": "53ebcf53-2ee4-4a26-ba2c-afc62091a148",
      "ike_version": 1,
      "key_lifetime": 28800,
      "name": "my-new-ike-policy",
      "negotiation_mode": "main",
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      }
    }

Lists all the connections that use the specified policy

This request lists all the connections that use the specified policy.

GET /ike_policies/{id}/connections
Request

Path Parameters

  • The IKE policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

  • A policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all IPsec policies

This request retrieves a paginated list of all IPsec policies that belong to this account.

GET /ipsec_policies
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • curl -X GET \
    "$rias_endpoint/v1/ipsec_policies?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IPsec policies were retrieved successfully.

Example responses
  • {
      "ipsec_policies": [
        {
          "authentication_algorithm": "md5",
          "created_at": "2018-12-13T19:34:16.961597Z",
          "encapsulation_mode": "tunnel",
          "encryption_algorithm": "aes256",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7",
          "id": "43c2f663-3960-4289-9253-f6eab23a6cd7",
          "key_lifetime": 28800,
          "name": "my-ipsec-policy-1",
          "pfs": "disabled",
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          },
          "transform_protocol": "esp"
        },
        {
          "authentication_algorithm": "md5",
          "created_at": "2018-12-13T19:34:08.719912Z",
          "encapsulation_mode": "tunnel",
          "encryption_algorithm": "aes256",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
          "id": "a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
          "key_lifetime": 28800,
          "name": "my-ipsec-policy-2",
          "pfs": "disabled",
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          },
          "transform_protocol": "esp"
        }
      ]
    }

Create an IPsec policy

This request creates a new IPsec policy.

POST /ipsec_policies
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The IPsec policy template.

  • curl -X POST \
    "$rias_endpoint/v1/ipsec_policies?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "authentication_algorithm": "md5",
          "encryption_algorithm": "aes256",
          "key_lifetime": 28800,
          "name": "my-ipsec-policy-2",
          "pfs": "disabled",
          "resource_group": {
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          }
        }'
Response

Status Code

  • The IPsec policy was created successfully.

  • An invalid IPsec policy template was provided.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:34:08.719912Z",
      "encapsulation_mode": "tunnel",
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "id": "a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "key_lifetime": 28800,
      "name": "my-ipsec-policy-2",
      "pfs": "disabled",
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      },
      "transform_protocol": "esp"
    }

Delete an IPsec policy

This request deletes an IPsec policy. This operation cannot be reversed.

DELETE /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IPsec policy was deleted successfully.

  • An IPsec policy with the specified identifier could not be found.

  • The IPsec policy is in use and cannot be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified IPsec policy

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

GET /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The IPsec policy was retrieved successfully.

  • An IPsec policy with the specified identifier could not be found.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:34:08.719912Z",
      "encapsulation_mode": "tunnel",
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "id": "a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "key_lifetime": 28800,
      "name": "my-ipsec-policy-2",
      "pfs": "disabled",
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      },
      "transform_protocol": "esp"
    }

Update an IPsec policy

This request updates the properties of an existing IPsec policy.

PATCH /ipsec_policies/{id}
Request

Path Parameters

  • The IPsec policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The IPsec policy patch.

  • curl -X PATCH \
    "$rias_endpoint/v1/ipsec_policies/$ipsec_policy_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name":"my-new-ipsec-policy" }'
Response

Status Code

  • The IPsec policy was updated successfully.

  • An invalid IPsec policy patch was provided.

  • An IPsec policy with the specified identifier could not be found.

Example responses
  • {
      "authentication_algorithm": "md5",
      "created_at": "2018-12-13T19:34:08.719912Z",
      "encapsulation_mode": "tunnel",
      "encryption_algorithm": "aes256",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "id": "a4c47690-bc52-45df-9bbd-a1f2b814a8ac",
      "key_lifetime": 28800,
      "name": "my-new-ipsec-policy",
      "pfs": "disabled",
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/56969d60-43e9-465c-883c-b9f7363e78e8",
        "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
      },
      "transform_protocol": "esp"
    }

Lists all the connections that use the specified policy

This request lists all the connections that use the specified policy.

GET /ipsec_policies/{id}/connections
Request

Path Parameters

  • The IPsec policy identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

  • A policy with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List all VPN gateways

This request retrieves a paginated list of all VPN gateways that belong to this account.

GET /vpn_gateways
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

  • curl -X GET \
    "$rias_endpoint/v1/vpn_gateways?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The VPN gateways were retrieved successfully.

Example responses
  • {
      "vpn_gateways": [
        {
          "connections": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/bb7baa8f-e4e2-45f5-9286-aac4139d5e78/connections/9736b5a9-0244-475b-a008-ef75a4d72e67",
            "id": "9736b5a9-0244-475b-a008-ef75a4d72e67",
            "name": "my-vpn-connection"
          },
          "created_at": "2018-12-13T19:50:40.740442Z",
          "crn": "crn:[...]",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/bb7baa8f-e4e2-45f5-9286-aac4139d5e78",
          "id": "bb7baa8f-e4e2-45f5-9286-aac4139d5e78",
          "name": "my-vpn-gateway-1",
          "public_ip": {
            "address": "0.0.0.0"
          },
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/2093bc307ba540aabeea706937a26df7",
            "id": "2093bc307ba540aabeea706937a26df7"
          },
          "status": "pending",
          "subnet": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2d746293-8d39-4123-a966-cdb2ec50e7ba",
            "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba",
            "name": "my-subnet-1"
          }
        },
        {
          "connections": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
            "id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
            "name": "my-vpn-connection"
          },
          "created_at": "2018-12-13T19:38:05.70368Z",
          "crn": "crn:[...]",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9",
          "id": "a7d258d5-be1e-491d-83db-526d8d9a2ce9",
          "name": "my-vpn-gateway-2",
          "public_ip": {
            "address": "0.0.0.0"
          },
          "resource_group": {
            "href": "https://resource-manager.bluemix.net/v1/resource_groups/2093bc307ba540aabeea706937a26df7",
            "id": "2093bc307ba540aabeea706937a26df7"
          },
          "status": "pending",
          "subnet": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2d746293-8d39-4123-a966-cdb2ec50e7ba",
            "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba",
            "name": "my-subnet-1"
          }
        }
      ]
    }

Create a VPN gateway

This request creates a new VPN gateway.

POST /vpn_gateways
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The VPN gateway template.

  • curl -X POST \
    "$rias_endpoint/v1/vpn_gateways?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "name": "my-new-vpn-gateway",
          "subnet": {
            "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba"
          },
          "resource_group": {
            "id": "56969d60-43e9-465c-883c-b9f7363e78e8"
          }
        }'
Response

Status Code

  • The VPN gateway was created successfully.

  • An invalid VPN gateway template was provided.

Example responses
  • {
      "created_at": "2018-12-13T17:29:36.921569Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/e630bb38-c3a7-4619-b0e5-7bff14e060fe",
      "id": "e630bb38-c3a7-4619-b0e5-7bff14e060fe",
      "name": "my-new-vpn-gateway",
      "public_ip": {
        "address": "0.0.0.0"
      },
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/2093bc307ba540aabeea706937a26df7",
        "id": "2093bc307ba540aabeea706937a26df7"
      },
      "status": "pending",
      "subnet": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "name": "my-subnet-1"
      }
    }

Delete a VPN gateway

This request deletes a VPN gateway. A VPN gateway with a status of pending cannot be deleted. This operation deletes all VPN connections associated with this VPN gateway. This operation cannot be reversed.

DELETE /vpn_gateways/{id}
Request

Path Parameters

  • The VPN gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The VPN gateway deletion request has been accepted.

  • A VPN gateway with the specified identifier could not be found.

  • The VPN gateway is not allowed to be deleted.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified VPN gateway

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

GET /vpn_gateways/{id}
Request

Path Parameters

  • The VPN gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The VPN gateway was retrieved successfully.

  • A VPN gateway with the specified identifier could not be found.

Example responses
  • {
      "connections": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
        "id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
        "name": "my-vpn-connection"
      },
      "created_at": "2018-12-13T19:38:05.70368Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9",
      "id": "a7d258d5-be1e-491d-83db-526d8d9a2ce9",
      "name": "my-vpn-gateway-2",
      "public_ip": {
        "address": "0.0.0.0"
      },
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/2093bc307ba540aabeea706937a26df7",
        "id": "2093bc307ba540aabeea706937a26df7"
      },
      "status": "pending",
      "subnet": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "name": "my-subnet-1"
      }
    }

Update a VPN gateway

This request updates the properties of an existing VPN gateway.

PATCH /vpn_gateways/{id}
Request

Path Parameters

  • The VPN gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The VPN gateway patch.

  • curl -X PATCH \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name": "my-vpn-gateway-1" }'
Response

Status Code

  • The VPN gateway was updated successfully.

  • An invalid VPN gateway patch was provided.

  • A VPN gateway with the specified identifier could not be found.

Example responses
  • {
      "created_at": "2018-12-13T17:29:36.921569Z",
      "crn": "crn:[...]",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/e630bb38-c3a7-4619-b0e5-7bff14e060fe",
      "id": "e630bb38-c3a7-4619-b0e5-7bff14e060fe",
      "name": "my-vpn-gateway-1",
      "public_ip": {
        "address": "0.0.0.0"
      },
      "resource_group": {
        "href": "https://resource-manager.bluemix.net/v1/resource_groups/2093bc307ba540aabeea706937a26df7",
        "id": "2093bc307ba540aabeea706937a26df7"
      },
      "status": "pending",
      "subnet": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/subnets/2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "id": "2d746293-8d39-4123-a966-cdb2ec50e7ba",
        "name": "my-subnet-1"
      }
    }

List all the connections of a VPN gateway

This request lists all the connections of a particular VPN gateway.

GET /vpn_gateways/{vpn_gateway_id}/connections
Request

Path Parameters

  • The VPN gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • Filters the collection to VPN connections with the specified status

Response

Collection of VPN connections in a VPN gateway

Status Code

  • The VPN connections were retrieved successfully.

  • A VPN gateway with the specified identifier could not be found.

Example responses
  • {
      "connections": [
        {
          "admin_state_up": true,
          "authentication_mode": "psk",
          "created_at": "2018-12-13T19:40:12.124082Z",
          "dead_peer_detection": {
            "action": "none",
            "interval": 15,
            "timeout": 30
          },
          "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
          "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
          "local_cidrs": [
            "192.0.2.50/24"
          ],
          "name": "my-vpn-connection-1",
          "peer_address": "192.0.2.5",
          "peer_cidrs": [
            "192.0.2.40/24"
          ],
          "psk": "C4vVf9wVvyliXhdsDBmvM",
          "route_mode": "policy",
          "status": "down"
        },
        {
          "admin_state_up": true,
          "authentication_mode": "psk",
          "created_at": "2018-12-13T19:39:47.938464Z",
          "dead_peer_detection": {
            "action": "none",
            "interval": 15,
            "timeout": 30
          },
          "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
          "id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
          "ike_policy": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d",
            "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d",
            "name": "my-ike-policy"
          },
          "ipsec_policy": {
            "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7",
            "id": "43c2f663-3960-4289-9253-f6eab23a6cd7",
            "name": "my-ipsec-policy"
          },
          "local_cidrs": [
            "192.0.2.50/24"
          ],
          "name": "my-vpn-connection-2",
          "peer_address": "192.0.2.5",
          "peer_cidrs": [
            "192.0.2.40/24"
          ],
          "psk": "C4vVf9wVvyliXhdsDBmvM",
          "route_mode": "policy",
          "status": "down"
        }
      ]
    }

Create a VPN connection

This request creates a new VPN connection.

POST /vpn_gateways/{vpn_gateway_id}/connections
Request

Path Parameters

  • The VPN gateway identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The VPN connection template.

  • curl -X POST \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "admin_state_up": true,
          "dead_peer_detection": {
            "interval": 15,
            "timeout": 30
          },
          "local_cidrs": ["192.0.2.50/24"],
          "ike_policy": {
            "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d"
          },
          "ipsec_policy": {
            "id": "43c2f663-3960-4289-9253-f6eab23a6cd7"
          },
          "name": "my-vpn-connection-2",
          "peer_address": "192.0.2.5",
          "peer_cidrs": ["192.0.2.40/24"],
          "psk": "C4vVf9wVvyliXhdsDBmvM"
        }'
Response

Status Code

  • The VPN connection was created successfully.

  • An invalid VPN connection template was provided.

Example responses
  • {
      "admin_state_up": true,
      "authentication_mode": "psk",
      "created_at": "2018-12-13T19:39:47.938464Z",
      "dead_peer_detection": {
        "action": "none",
        "interval": 15,
        "timeout": 30
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/b67efb2c-bd17-457d-be8e-7b46404062dc",
      "id": "b67efb2c-bd17-457d-be8e-7b46404062dc",
      "ike_policy": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/ike_policies/e98f46a3-1e4e-4195-b4e5-b8155192689d",
        "id": "e98f46a3-1e4e-4195-b4e5-b8155192689d",
        "name": "my-ike-policy"
      },
      "ipsec_policy": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/ipsec_policies/43c2f663-3960-4289-9253-f6eab23a6cd7",
        "id": "43c2f663-3960-4289-9253-f6eab23a6cd7",
        "name": "my-ipsec-policy"
      },
      "local_cidrs": [
        "192.0.2.50/24"
      ],
      "name": "my-vpn-connection-2",
      "peer_address": "192.0.2.5",
      "peer_cidrs": [
        "192.0.2.40/24"
      ],
      "psk": "C4vVf9wVvyliXhdsDBmvM",
      "route_mode": "policy",
      "status": "down"
    }

Delete a VPN connection

This request deletes a VPN connection. This operation cannot be reversed.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The VPN connection deletion request has been accepted.

  • A VPN connection with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified VPN connection

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

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The VPN connection was retrieved successfully.

  • A VPN connection with the specified identifier could not be found.

Example responses
  • {
      "admin_state_up": true,
      "authentication_mode": "psk",
      "created_at": "2018-12-13T19:40:12.124082Z",
      "dead_peer_detection": {
        "action": "none",
        "interval": 15,
        "timeout": 30
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
      "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
      "local_cidrs": [
        "192.0.2.50/24"
      ],
      "name": "my-vpn-connection-1",
      "peer_address": "192.0.2.5",
      "peer_cidrs": [
        "192.0.2.40/24"
      ],
      "psk": "C4vVf9wVvyliXhdsDBmvM",
      "route_mode": "policy",
      "status": "down"
    }

Update a VPN connection

This request updates the properties of an existing VPN connection.

PATCH /vpn_gateways/{vpn_gateway_id}/connections/{id}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The VPN connection patch.

  • curl -X PATCH \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name": "my-vpn-connection-1"}'
Response

Status Code

  • The VPN connection was updated successfully.

  • An invalid VPN connection patch was provided.

  • A VPN connection with the specified identifier could not be found.

Example responses
  • {
      "admin_state_up": true,
      "authentication_mode": "psk",
      "created_at": "2018-12-13T19:40:12.124082Z",
      "dead_peer_detection": {
        "action": "none",
        "interval": 15,
        "timeout": 30
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/vpn_gateways/a7d258d5-be1e-491d-83db-526d8d9a2ce9/connections/52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
      "id": "52f69dc3-6a5c-4bcf-b264-e7fae279b15c",
      "local_cidrs": [
        "192.0.2.50/24"
      ],
      "name": "my-vpn-connection-1",
      "peer_address": "192.0.2.5",
      "peer_cidrs": [
        "192.0.2.40/24"
      ],
      "psk": "C4vVf9wVvyliXhdsDBmvM",
      "route_mode": "policy",
      "status": "down"
    }

List all local CIDRs for a resource

This request lists all local CIDRs for the resource specified by the identifier in the URL.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/local_cidrs?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The CIDRs were retrieved successfully.

  • A resource with the specified identifier could not be found.

Example responses
  • {
      "local_cidrs": [
        "0.0.19.0/24"
      ]
    }

Remove a CIDR from a resource

This request removes a CIDR from a resource.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The CIDR was successfully removed from the resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Check if a specific CIDR exists on a specific resource

This request succeeds if a CIDR exists on the resource and fails otherwise.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The specified CIDR exists on the specified resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Set a CIDR on a resource

This request adds the specified CIDR to the specified resource. A request body is not required, and if supplied, is ignored. This request succeeds if the CIDR already exists on the resource.

PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/local_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The CIDR was successfully set on the resource.

  • The supplied CIDR was invalid.

  • The specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

List all peer CIDRs for a resource

This request lists all peer CIDRs for the resource specified by the identifier in the URL.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/vpn_gateways/$vpn_gateway_id/connections/$connection_id/peer_cidrs?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The CIDRs were retrieved successfully.

  • A resource with the specified identifier could not be found.

Example responses
  • {
      "peer_cidrs": [
        "0.0.150.0/24"
      ]
    }

Remove a CIDR from a resource

This request removes a CIDR from a resource.

DELETE /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The CIDR was successfully removed from the resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Check if a specific CIDR exists on a specific resource

This request succeeds if a CIDR exists on the resource and fails otherwise.

GET /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The specified CIDR exists on the specified resource.

  • The specified CIDR does not exist on the specified resource or the specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

Set a CIDR on a resource

This request adds the specified CIDR to the specified resource. A request body is not required, and if supplied, is ignored. This request succeeds if the CIDR already exists on the resource.

PUT /vpn_gateways/{vpn_gateway_id}/connections/{id}/peer_cidrs/{prefix_address}/{prefix_length}
Request

Path Parameters

  • The VPN gateway identifier

  • The VPN connection identifier

  • The prefix address part of the CIDR

  • The prefix length part of the CIDR

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

Response

Status Code

  • The CIDR was successfully set on the resource.

  • The supplied CIDR was invalid.

  • The specified resource could not be found.

No Sample Response

This method does not specify any sample responses.

List all images

This request lists all images available in the region. An image provides source data for a volume. Images are either system-provided, or created from another source, such as importing from object storage.

GET /images
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • Filters the collection to resources within one of the resource groups identified in a comma-separated list of resource group identifiers

  • Filters the collection to images with the specified visibility

    Allowable values: [private,public]

  • curl -X GET \
    "$rias_endpoint/v1/images?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • Images retrieved successfully

Example responses
  • {
      "first": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/images?limit=50"
      },
      "images": [
        {
          "created_at": "2019-03-15T21:31:37Z",
          "crn": "crn:v1:bluemix:public:is:us-south:::image:5ccbc579-dc22-0def-46a8-9c2e9b502d37",
          "file": {},
          "href": "https://us-south.iaas.cloud.ibm.com/v1/images/5ccbc579-dc22-0def-46a8-9c2e9b502d37",
          "id": "5ccbc579-dc22-0def-46a8-9c2e9b502d37",
          "minimum_provisioned_size": 100,
          "name": "windows-2016-amd64",
          "operating_system": {
            "architecture": "amd64",
            "display_name": "Windows Server 2016 Standard Edition (64 bit)",
            "family": "Windows Server",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/windows-2016-amd64",
            "name": "windows-2016-amd64",
            "vendor": "Microsoft",
            "version": "2016 Standard Edition"
          },
          "status": "available",
          "visibility": "public"
        },
        {
          "created_at": "2018-10-04T04:04:25Z",
          "crn": "crn:v1:bluemix:public:is:us-south:::image:e15b69f1-c701-f621-e752-70eda3df5695",
          "file": {},
          "href": "https://us-south.iaas.cloud.ibm.com/v1/images/e15b69f1-c701-f621-e752-70eda3df5695",
          "id": "e15b69f1-c701-f621-e752-70eda3df5695",
          "minimum_provisioned_size": 100,
          "name": "debian-9.x-amd64",
          "operating_system": {
            "architecture": "amd64",
            "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
            "family": "Debian GNU/Linux",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64",
            "name": "debian-9-amd64",
            "vendor": "Debian",
            "version": "9.x Stretch/Stable - Minimal Install"
          },
          "status": "available",
          "visibility": "public"
        },
        {
          "created_at": "2018-12-12T18:22:51Z",
          "crn": "crn:v1:bluemix:public:is:eu-de:::image:7eb4e35b-4257-56f8-d7da-326d85452591",
          "file": {},
          "href": "https://eu-de.iaas.cloud.ibm.com/v1/images/7eb4e35b-4257-56f8-d7da-326d85452591",
          "id": "7eb4e35b-4257-56f8-d7da-326d85452591",
          "minimum_provisioned_size": 100,
          "name": "ubuntu-16.04-amd64",
          "operating_system": {
            "architecture": "amd64",
            "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
            "family": "Ubuntu Linux",
            "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/ubuntu-16-04-amd64",
            "name": "ubuntu-16-04-amd64",
            "vendor": "Canonical",
            "version": "16.04 LTS Xenial Xerus Minimal Install"
          },
          "status": "available",
          "visibility": "public"
        }
      ],
      "limit": 50
    }

Create an image

This request creates a new image from an image template. The image template object is structured in the same way as a retrieved image, and contains the information necessary to create the new image. A URL to the image file on object storage must be provided.

POST /images
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The image template

  • curl -X POST \
    "$rias_endpoint/v1/images?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{
          "name": "my-image",
          "file": {
            "href": "cos://us-south/my-bucket/my-image.vhd"
          },
          "operating_system": {
            "name": "debian-9-amd64"
          }
        }'
Response

Status Code

  • Image created successfully

  • The supplied image template was invalid.

Example responses
  • {
      "created_at": "2019-06-26T00:05:13.873893Z",
      "crn": "crn:[...]",
      "file": {},
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72251a2e-d6c5-42b4-97b0-b5f8e8d1f479",
      "id": "72251a2e-d6c5-42b4-97b0-b5f8e8d1f479",
      "name": "my-image",
      "operating_system": {
        "architecture": "amd64",
        "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
        "family": "Debian GNU/Linux",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64",
        "name": "debian-9-amd64",
        "vendor": "Debian",
        "version": "9.x Stretch/Stable - Minimal Install"
      },
      "resource_group": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771",
        "id": "3fad3f2204eb4998c3964d254ffcd771"
      },
      "status": "pending",
      "visibility": "private"
    }

Delete specified image

This request deletes an image. This operation cannot be reversed. System-provided images are not allowed to be deleted. An image with a status of pending, tentative, or deleting cannot be deleted.

DELETE /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X DELETE \
    "$rias_endpoint/v1/images/$image_id?2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The image deletion request was accepted.

  • The image is not allowed to be deleted.

  • An image with the specified identifier could not be found.

  • The image cannot be deleted in its current state.

No Sample Response

This method does not specify any sample responses.

Retrieve the specified image

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

GET /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/images/$image_id?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • Image retrieved successfully

  • An image with the specified identifier could not be found.

Example responses
  • {
      "created_at": "2019-06-26T00:05:13.873893Z",
      "crn": "crn:[...]",
      "file": {
        "size": 10
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72251a2e-d6c5-42b4-97b0-b5f8e8d1f479",
      "id": "72251a2e-d6c5-42b4-97b0-b5f8e8d1f479",
      "minimum_provisioned_size": 100,
      "name": "my-image",
      "operating_system": {
        "architecture": "amd64",
        "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
        "family": "Debian GNU/Linux",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64",
        "name": "debian-9-amd64",
        "vendor": "Debian",
        "version": "9.x Stretch/Stable - Minimal Install"
      },
      "resource_group": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/3fad3f2204eb4998c3964d254ffcd771",
        "id": "3fad3f2204eb4998c3964d254ffcd771"
      },
      "status": "available",
      "visibility": "private"
    }

Update specified image

This request updates an image with the information in a provided image patch. The image patch object is structured in the same way as a retrieved image and contains only the information to be updated. System-provided images are not allowed to be updated. An image with a status of deleting cannot be updated.

PATCH /images/{id}
Request

Path Parameters

  • The image identifier

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

The image patch

  • curl -X PATCH \
    "$rias_endpoint/v1/images/$image_id?2020-01-28&generation=2" \
    -H "Authorization: $iam_token" \
    -d '{ "name" : "my-image-patched" }'
Response

Status Code

  • Image updated successfully

  • The supplied image template was invalid.

  • The image is not allowed to be updated.

  • An image with the specified identifier could not be found.

  • The image cannot be updated in its current state.

Example responses
  • {
      "created_at": "2019-06-24T21:34:08.39622Z",
      "crn": "crn:[...]",
      "file": {
        "size": 10
      },
      "href": "https://us-south.iaas.cloud.ibm.com/v1/images/f2ecdc05-452b-4b9a-ab18-7e129f730c15",
      "id": "f2ecdc05-452b-4b9a-ab18-7e129f730c15",
      "minimum_provisioned_size": 100,
      "name": "my-image-patched",
      "operating_system": {
        "architecture": "amd64",
        "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
        "family": "Debian GNU/Linux",
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64",
        "name": "debian-9-amd64",
        "vendor": "Debian",
        "version": "9.x Stretch/Stable - Minimal Install"
      },
      "resource_group": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/resource_groups/7acd0e2240ea4965a9387d209ffcd896",
        "id": "7acd0e2240ea4965a9387d209ffcd896"
      },
      "status": "available",
      "visibility": "private"
    }

Retrieves all operating systems

This request retrieves all operating systems.

GET /operating_systems
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

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

  • The number of resources to return on a page

    Constraints: 1 ≤ value ≤ 100

    Default: 50

  • curl -X GET \
    "$rias_endpoint/v1/operating_systems?2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The operating systems were retrieved successfully.

Example responses
  • {
      "first": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems?limit=4"
      },
      "limit": 4,
      "operating_systems": [
        {
          "architecture": "amd64",
          "display_name": "CentOS 7.x - Minimal Install (64 bit)",
          "family": "CentOS",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/centos-7-amd64",
          "name": "centos-7-amd64",
          "vendor": "CentOS",
          "version": "7.x - Minimal Install"
        },
        {
          "architecture": "amd64",
          "display_name": "Debian GNU/Linux 8.x jessie/Stable - Minimal Install (64 bit)",
          "family": "Debian GNU/Linux",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-8-amd64",
          "name": "debian-8-amd64",
          "vendor": "Debian",
          "version": "8.x jessie/Stable - Minimal Install"
        },
        {
          "architecture": "amd64",
          "display_name": "Debian GNU/Linux 9.x Stretch/Stable - Minimal Install (64 bit)",
          "family": "Debian GNU/Linux",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/debian-9-amd64",
          "name": "debian-9-amd64",
          "vendor": "Debian",
          "version": "9.x Stretch/Stable - Minimal Install"
        },
        {
          "architecture": "amd64",
          "display_name": "Red Hat Enterprise Linux 7.x - Minimal Install (64 bit)",
          "family": "Red Hat Enterprise Linux",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-7-amd64",
          "name": "red-7-amd64",
          "vendor": "Red Hat"
        }
      ]
    }

Retrieves an operating system

This request retrieves a single operating system specified by the name in the URL.

GET /operating_systems/{name}
Request

Path Parameters

  • The operating system name

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/operating_system/$operating_system_name?2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • The operating system was retrieved successfully.

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

Example responses
  • {
      "architecture": "amd64",
      "display_name": "Red Hat Enterprise Linux 7.x - Minimal Install (64 bit)",
      "family": "Red Hat Enterprise Linux",
      "href": "https://us-south.iaas.cloud.ibm.com/v1/operating_systems/red-7-amd64",
      "name": "red-7-amd64",
      "vendor": "Red Hat",
      "version": "7.x - Minimal Install"
    }

List all instance profiles

This request lists all instance profiles available in the region. An instance profile specifies the performance characteristics and pricing model for an instance.

GET /instance/profiles
Request

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/instance/profiles?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response

Status Code

  • Instance profiles retrieved successfully

Example responses
  • {
      "first": {
        "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles?limit=3"
      },
      "limit": 3,
      "profiles": [
        {
          "crn": "crn:[...]",
          "family": "memory",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/m-62x496",
          "name": "m-62x496"
        },
        {
          "crn": "crn:[...]",
          "family": "balanced",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/b-62x248",
          "name": "b-62x248"
        },
        {
          "crn": "crn:[...]",
          "family": "cpu",
          "href": "https://us-south.iaas.cloud.ibm.com/v1/instance/profiles/c-2x4",
          "name": "c-2x4"
        }
      ],
      "total_count": 3
    }

Retrieve specified instance profile

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

GET /instance/profiles/{name}
Request

Path Parameters

  • The instance profile name

Query Parameters

  • Requests the version of the API as of a date in the format YYYY-MM-DD. Any date up to the current date may be provided. Specify the current date to request the latest version.

    Constraints: Value must match regular expression ^[0-9]{4}-[0-9]{2}-[0-9]{2}$

  • The infrastructure generation for the request. For the API behavior documented here, use 2.

    Allowable values: [2]

  • curl -X GET \
    "$rias_endpoint/v1/instance/profiles/$profile_name?version=2020-01-28&generation=2" \
    -H "Authorization: $iam_token"
Response