IBM Cloud API Docs

Introduction to the beta VPC instance metadata API

This reference includes the full IBM Cloud® Virtual Private Cloud (VPC) Instance Metadata API, as well as newly released open beta features. This reference may also include limited beta features for customer accounts with special approval to preview those features.

There are no backward-compatibility guarantees as a feature progresses through its beta phase, or from the final beta release to its initial GA release. Using features that are not GA mature could introduce the risk of corrupting resources in your account.

Read the introduction in the generally available VPC Instance Metadata API for details on endpoint URLs, authentication, auditing, error handling, versioning, and other important information.

Versioning

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.

This reference documents API behavior for any date value in the version parameter within 45 days of today’s date. To view the reference for any other supported versions of the API, select it from the Version list. See also Versioning in the VPC API.

Maturity query parameter

API requests accept a maturity query parameter. This parameter lets you decide on the level of stability to use before features become generally available.

API requests must specify a maturity=beta query parameter. Omitting maturity results in the GA version of the API being used, which can result in different behavior.

Example of using the maturity parameter in a request:

curl -X GET   "$vpc_metadata_api_endpoint/metadata/v1/instance?maturity=beta"   -H "Authorization: Bearer $iam_token"

Change log

Important changes to the beta metadata API, such as additions, updates, and deprecations, are documented in the Beta VPC Instance Metadata API change log.

Methods

Create an IAM token using an instance identity token

This request uses an instance identity access token, and a trusted profile linked to a virtual server instance (whether the default linked at instance creation time, or one provided in the request body) to generate an IAM access token.

POST /instance_identity/v1/iam_token

Auditing

Calling this method generates the following auditing event.

  • is.metadata.computeresource-token.request

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

The IAM access token prototype.

  • curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/iam_token?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token" -d '{
          "trusted_profile": {
            "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
          }
        }'

Response

Information about this instance identity IAM access token

Status Code

  • The IAM access token was successfully generated.

  • An invalid access token prototype object was provided.

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
      "created_at": "2021-03-22T14:10:15Z",
      "expires_at": "2021-03-22T15:10:15Z",
      "expires_in": 3600
    }
  • {
      "errors": [
        {
          "code": "profile_not_linked",
          "message": "The virtual server instance is not linked to the specified trusted profile",
          "more_info": "https://cloud.ibm.com/docs/vpc?topic=vpc-imd-trusted-profile-metadata",
          "target": {
            "name": "trusted_profile.id",
            "type": "field",
            "value": "Profile-dc557279-772b-4cf9-82e9-0d127c4d7ac9"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }

Create an instance identity access token

This request creates an access token for retrieving VPC metadata or using it to generate an IAM token using a trusted profile linked to the virtual server instance.

PUT /instance_identity/v1/token

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-identity-token.create

Request

Custom Headers

  • The metadata flavor. Currently, only ibm is supported.

    Allowable values: [ibm]

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

The access token prototype. A valid prototype object is required even if no properties are specified.

  • curl -X PUT "$vpc_metadata_api_endpoint/instance_identity/v1/token?version=2024-11-05&maturity=beta" -H "Metadata-Flavor: ibm" -d '{}'

Response

Information about this access token

Status Code

  • The access token was created successfully.

  • An invalid access token prototype object was provided.

Example responses
  • {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
      "created_at": "2021-03-22T15:09:45Z",
      "expires_at": "2021-03-22T15:10:15Z",
      "expires_in": 30
    }
  • {
      "errors": [
        {
          "code": "invalid_value",
          "message": "The value provided for the `expires_in` field must be between `5` and `3600`.",
          "more_info": "https://cloud.ibm.com/docs/vpc?topic=vpc-metadata-service#token-expires-in",
          "target": {
            "name": "expires_in",
            "type": "field",
            "value": "7200"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }

Create an instance identity certificate using an instance identity access token

This request uses an instance identity access token, and certificate signing request, to generate an instance identity certificate for the instance

POST /instance_identity/v1/certificates

Auditing

Calling this method generates the following auditing event.

  • is.metadata.certificate.create

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

The instance identity certificate prototype

  • curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/certificates?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token" -d '{
          "csr": |
            -----BEGIN CERTIFICATE REQUEST-----
            MIICzzCCAbcCAQAwgYkxCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGEx
            EjAQBgNVBAcMCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0
            dWFsIFByaXZhdGUgQ2xvdWQxJDAiBgNVBAMMG1ZQQyBFeGFtcGxlIEludGVybWVk
            aWF0ZSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY78TrUhSrC
            SpeLXgS4JF+PpssYQpc9kJoOTJzUPqMocja6WL4xt/jvg60lCik185lkpClP+gSp
            h0DzXaXeMpm29HBu8JqXFN2I460jRYHf6NwhCvTO/qHyLkLU11zVEFl+a298AahA
            NU1ms1U2aaYYYXBkPLtN1Uyr6BeEtgyOi926wySdMNQzPSLGmgdpkuuFWDCI94y6
            8t/a8hhKGKtWtLQuAvXxE91eTZlJyETalQ5xhpGAcv+e1UQAlF8V3ELlunqD2BpO
            h6N3ipct+HopRdp/cQ/2weNUeDc2sTv9JR6vnGiOa9VpZ017RRPMC6RaGDJLgtKo
            igXrMrsnn9kCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQBCb71iIsm+ak94qO2+
            n7+WYLkIPCyIDb5mBCqJi5AL1ZC+WqbNVf4NqC6zS9qJbeQGOId5sGVLkdJjcccg
            f6SrE0mrC1h43ttwkZGNWML+rO0OlEuEDYdfsUQuH24t9KQNf2c6pmdLdchNovFz
            blhmHdjcUUAVYHHrFPgT0uvQVYEFLLIGa2ZHVeTJvZf4IVW2SiezSt/d6NsHi3s1
            rVZ8UIXXaFsOkgF65+D14hW+t9GzajSYY/IlU4E5YCRO9lHM/YmlbQRNXJgHDMta
            /uh2hhK3mMR7sfeBhHYvqs1hxBaLEka5rKOO61q8Px9eCC+WZx2nyHFILp86RyT0
            mL9R
            -----END CERTIFICATE REQUEST-----
        }'

Response

Information about this instance identity certificate

Status Code

  • The instance identity certificate was created successfully.

  • An invalid instance identity certificate prototype object was provided.

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "certificates": [
        "-----BEGIN CERTIFICATE-----\nMIIDmTCCAoECFDGlhn2VlwNEQymsNpyt9rOiiiWDMA0GCSqGSIb3DQEBCwUAMIGJ\nMQswCQYDVQQGEwJVUzESMBAGA1UECAwJTWlubmVzb3RhMRIwEAYDVQQHDAlSb2No\nZXN0ZXIxDDAKBgNVBAoMA0lCTTEeMBwGA1UECwwVVmlydHVhbCBQcml2YXRlIENs\nb3VkMSQwIgYDVQQDDBtWUEMgRXhhbXBsZSBJbnRlcm1lZGlhdGUgQ0EwHhcNMjIx\nMTAxMTM1MDE0WhcNMjIxMTAxMTQyMDE0WjCBhzELMAkGA1UEBhMCVVMxEjAQBgNV\nBAgMCU1pbm5lc290YTESMBAGA1UEBwwJUm9jaGVzdGVyMQwwCgYDVQQKDANJQk0x\nHjAcBgNVBAsMFVZpcnR1YWwgUHJpdmF0ZSBDbG91ZDEiMCAGA1UEAwwZRXhhbXBs\nZSBTaGFyZSBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC\nggEBAM6JytY3R4zWo3zzw/dM9ldUw8TIDQ9dNt+0sm3bFHHlAXaSKvmI+Ls/uQoh\n9VPpRLTx+WyljnKNnkXC6BQOzlugjAfi8hE2f5CC0A0m58XcBiZqH5BwTeLI4vVZ\nO9pLySckkEtHcmFE4h70KS5+1jDApeOTTS6EJsQcal/AAVYg7PDyXr1jE2HTKxnt\nlXopB/+bvWmBQ2k50Km0h0D1n0Ipoqqwb1wwWCrzQ2ds2XNKCUGkCgN6buFiF2nN\nLYS1tsIaw6OsTx+VheNGlYdlOhMUVypCok9JQ85P4NU47O6YgITX1V63ewZBnn5p\napywqdg8K2X2YgU/tLdpl5Jz2ysCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEABuOX\npxGbBQPdG3VGkNCYScZUcxocqmx4mCegBFfv4PjWU2+eG+3JikB3YWwqD11hixQm\n5Qwge/zMXzuKPs5D4yyblpDJlq5Iz/0VMjEl2paCHg9nm5Z3QaSydFH3SCGwfvld\nRn9ib6DSw4a58hmqON+CiWUSSibQy46gUsqVvYhq2lJimejTAN2DlePY2su1xvNV\nAdmDjmvO7j7YV/eWk6r7OgcqtVaAovN3okaybwxf8sLAFxLzp/aUaqXL10qJ/ISz\nVL+UHN7t5WzjHdh2OjDXwz0BOyhdbjyNX8ptKd+E0O21PsFFe8ErfShDh00g/ERP\nzXuEUsCxzTyWRTm8GA==\n-----END CERTIFICATE-----\n",
        "-----BEGIN CERTIFICATE-----\nMIIEADCCAuigAwIBAgIUDzQruKqvBY7+CS6DL0u93Na6cLMwDQYJKoZIhvcNAQEL\nBQAwgYExCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGExEjAQBgNVBAcM\nCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0dWFsIFByaXZh\ndGUgQ2xvdWQxHDAaBgNVBAMME1ZQQyBFeGFtcGxlIFJvb3QgQ0EwHhcNMjIxMTAx\nMDM0OTI5WhcNMjcxMDMxMDM0OTI5WjCBiTELMAkGA1UEBhMCVVMxEjAQBgNVBAgM\nCU1pbm5lc290YTESMBAGA1UEBwwJUm9jaGVzdGVyMQwwCgYDVQQKDANJQk0xHjAc\nBgNVBAsMFVZpcnR1YWwgUHJpdmF0ZSBDbG91ZDEkMCIGA1UEAwwbVlBDIEV4YW1w\nbGUgSW50ZXJtZWRpYXRlIENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC\nAQEAxjvxOtSFKsJKl4teBLgkX4+myxhClz2Qmg5MnNQ+oyhyNrpYvjG3+O+DrSUK\nKTXzmWSkKU/6BKmHQPNdpd4ymbb0cG7wmpcU3YjjrSNFgd/o3CEK9M7+ofIuQtTX\nXNUQWX5rb3wBqEA1TWazVTZpphhhcGQ8u03VTKvoF4S2DI6L3brDJJ0w1DM9Isaa\nB2mS64VYMIj3jLry39ryGEoYq1a0tC4C9fET3V5NmUnIRNqVDnGGkYBy/57VRACU\nXxXcQuW6eoPYGk6Ho3eKly34eilF2n9xD/bB41R4NzaxO/0lHq+caI5r1WlnTXtF\nE8wLpFoYMkuC0qiKBesyuyef2QIDAQABo2YwZDAdBgNVHQ4EFgQU2MIYc9g4Z7Kj\n79u2HPGYyTk5QHwwHwYDVR0jBBgwFoAUVnTLKJHyjHUcRp22jx+d3uGqnrwwEgYD\nVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwDQYJKoZIhvcNAQELBQAD\nggEBADhOBfnBEaWVWCsZo3UR7UlP5/8i3mRgyFt4YkICPMacy2IcnDw8aoyjTO5b\n4BLO4J1m4AmcJnDJcFIEKLBSNbzsiDdP2rWIAAJKO4gKxdTArIuLgq7zrR74j46L\nn6IFwumKQRw0diGYD6wWIo/f9kGy1NQ46igmRYrEfzA5HWitEpF0mu6lz8mZ8m9s\na6CTEqwLFhP+qOcWtpGjNTa+OHENAmmAR4mR4Os4MsBBnb4RA//S/4suW419Cz8N\n1/Ul7KduYRKpRMSiS9YWbCvC5WiEvOvfp8Z4ecXlC+ohU5MLuCRPfP+blBvxNx2O\nsLotlbzDpim/gYiJCHgW3POlsLE=\n-----END CERTIFICATE-----\n"
      ],
      "created_at": "2022-11-01T13:50:14Z",
      "expires_at": "2022-11-01T14:20:14Z",
      "expires_in": 1800,
      "id": "9fd84246-7df4-4667-94e4-8ecde51d5ac5"
    }
  • {
      "errors": [
        {
          "code": "invalid_value",
          "message": "The value provided for the `expires_in` field must be between `300` and `3600`.",
          "more_info": "https://cloud.ibm.com/apidocs/vpc-metadata#create-certificate-request",
          "target": {
            "name": "expires_in",
            "type": "field",
            "value": "7200"
          }
        }
      ],
      "status_code": 400,
      "trace": "e37872f6-f9a4-4084-a1a8-e56a1c8c8d3d"
    }

Retrieve the instance

This requests retrieves information for the calling instance.

GET /metadata/v1/instance

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance.read

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The instance was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "availability_policy": {
        "host_failure": "restart"
      },
      "bandwidth": 4000,
      "boot_volume_attachment": {
        "device": {
          "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb"
        },
        "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
        "name": "my-volume-attachment",
        "volume": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
          "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
          "name": "my-volume",
          "resource_type": "volume"
        }
      },
      "confidential_compute_mode": "sgx",
      "created_at": "2020-03-26T16:11:57Z",
      "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0",
      "dedicated_host": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "name": "my-dedicated-host",
        "resource_type": "dedicated_host"
      },
      "disks": [],
      "enable_secure_boot": true,
      "health_reasons": [],
      "health_state": "ok",
      "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0",
      "image": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
        "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
        "name": "my-image",
        "resource_type": "image"
      },
      "lifecycle_reasons": [],
      "lifecycle_state": "stable",
      "memory": 8,
      "metadata_service": {
        "enabled": true,
        "protocol": "http",
        "response_hop_limit": 1
      },
      "name": "my-instance",
      "network_attachments": [
        {
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-attachment",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "name": "my-virtual-network-interface",
            "resource_type": "virtual_network_interface"
          }
        }
      ],
      "network_interfaces": [
        {
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-interface",
          "primary_ipv4_address": "10.0.1.5",
          "resource_type": "network_interface",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          }
        }
      ],
      "numa_count": 2,
      "placement_target": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a",
        "name": "my-dedicated-host",
        "resource_type": "dedicated_host"
      },
      "primary_network_attachment": {
        "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
        "name": "my-instance-network-attachment",
        "primary_ip": {
          "address": "10.0.1.5",
          "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
          "name": "my-reserved-ip",
          "resource_type": "subnet_reserved_ip"
        },
        "resource_type": "instance_network_attachment",
        "subnet": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "name": "my-subnet",
          "resource_type": "subnet"
        },
        "virtual_network_interface": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "name": "my-virtual-network-interface",
          "resource_type": "virtual_network_interface"
        }
      },
      "primary_network_interface": {
        "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
        "name": "my-instance-network-interface",
        "primary_ipv4_address": "10.0.1.5",
        "resource_type": "network_interface",
        "subnet": {
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
          "name": "my-subnet",
          "resource_type": "subnet"
        }
      },
      "profile": {
        "name": "bx2-4x16",
        "resource_type": "instance_profile"
      },
      "reservation_affinity": {
        "policy": "disabled",
        "pool": []
      },
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "instance",
      "startable": true,
      "status": "running",
      "status_reasons": [],
      "total_network_bandwidth": 3000,
      "total_volume_bandwidth": 1000,
      "vcpu": {
        "architecture": "amd64",
        "count": 2,
        "manufacturer": "intel"
      },
      "volume_attachments": [
        {
          "device": {
            "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb"
          },
          "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
          "name": "my-volume-attachment",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "name": "my-volume",
            "resource_type": "volume"
          }
        },
        {
          "device": {
            "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8"
          },
          "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70",
          "name": "my-volume-attachment-2",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392",
            "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392",
            "name": "my-volume-2",
            "resource_type": "volume"
          }
        }
      ],
      "vpc": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "name": "my-vpc",
        "resource_type": "vpc"
      },
      "zone": {
        "name": "us-south-1"
      }
    }

Retrieve initialization information

This request retrieves initialization information for the calling instance.

GET /metadata/v1/instance/initialization

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-initialization.read

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The initialization information was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "default_trusted_profile": {
        "auto_link": true,
        "target": {
          "crn": "crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5",
          "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5",
          "resource_type": "trusted_profile"
        }
      },
      "keys": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
          "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "name": "my-key-1"
        }
      ],
      "user_data": "[...]"
    }

List network attachments

This request lists network attachments for the calling instance.

GET /metadata/v1/instance/network_attachments

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-attachment.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The instance network attachments were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "network_attachments": [
        {
          "created_at": "2023-09-30T23:42:32.993Z",
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "lifecycle_state": "stable",
          "name": "my-instance-network-attachment",
          "port_speed": 1000,
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "type": "primary",
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
            "name": "my-virtual-network-interface",
            "resource_type": "virtual_network_interface"
          }
        },
        {
          "created_at": "2023-09-30T23:42:33.366Z",
          "id": "0717-822a3789-61d5-4b8e-82c5-4310e6b7dc1b",
          "lifecycle_state": "stable",
          "name": "my-instance-network-attachment-2",
          "port_speed": 1000,
          "primary_ip": {
            "address": "10.0.2.10",
            "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749",
            "name": "my-reserved-ip-2",
            "resource_type": "subnet_reserved_ip"
          },
          "resource_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "name": "my-subnet-2",
            "resource_type": "subnet"
          },
          "type": "secondary",
          "virtual_network_interface": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
            "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
            "name": "my-virtual-network-interface-2",
            "resource_type": "virtual_network_interface"
          }
        }
      ]
    }

Retrieve a network attachment

This request retrieves a network attachment for the calling instance.

GET /metadata/v1/instance/network_attachments/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-attachment.read

Request

Path Parameters

  • The instance network attachment identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The instance network attachment was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A network attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2023-09-30T23:42:32.993Z",
      "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
      "lifecycle_state": "stable",
      "name": "my-instance-network-attachment",
      "port_speed": 1000,
      "primary_ip": {
        "address": "10.0.1.5",
        "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
        "name": "my-reserved-ip",
        "resource_type": "subnet_reserved_ip"
      },
      "resource_type": "instance_network_attachment",
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary",
      "virtual_network_interface": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
        "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
        "name": "my-virtual-network-interface",
        "resource_type": "virtual_network_interface"
      }
    }

List instance network interfaces

This request lists network interfaces for the calling instance.

GET /metadata/v1/instance/network_interfaces

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-interface.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The instance network interfaces were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "network_interfaces": [
        {
          "allow_ip_spoofing": false,
          "created_at": "2024-10-15T03:24:32.993Z",
          "floating_ips": [
            {
              "address": "203.0.113.1",
              "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
              "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
              "name": "my-floating-ip"
            }
          ],
          "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
          "name": "my-instance-network-interface",
          "port_speed": 1000,
          "primary_ipv4_address": "10.0.1.5",
          "resource_type": "network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "status": "available",
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "type": "primary"
        }
      ]
    }

Retrieve an instance network interface

This request retrieves a network interface for the calling instance.

GET /metadata/v1/instance/network_interfaces/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-network-interface.read

Request

Path Parameters

  • The instance network interface identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The instance network interface was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • An instance network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "allow_ip_spoofing": false,
      "created_at": "2024-10-15T03:24:32.993Z",
      "floating_ips": [
        {
          "address": "203.0.113.1",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
          "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd",
          "name": "my-floating-ip"
        }
      ],
      "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7",
      "name": "my-instance-network-interface",
      "port_speed": 1000,
      "primary_ipv4_address": "10.0.1.5",
      "resource_type": "network_interface",
      "security_groups": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "name": "my-security-group"
        }
      ],
      "status": "available",
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary"
    }

List volume attachments

This request lists volume attachments for the calling instance.

GET /metadata/v1/instance/volume_attachments

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-volume-attachment.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The volume attachments were retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

Example responses
  • {
      "volume_attachments": [
        {
          "bandwidth": 250,
          "created_at": "2024-10-24T16:32:05.000Z",
          "delete_volume_on_instance_delete": true,
          "device": {
            "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8"
          },
          "id": "0717-fdb3642d-c849-4c29-97a9-03b868616f88",
          "name": "my-boot-volume-attachment",
          "status": "attached",
          "type": "boot",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-89b05e9a-e635-9464-9747-7ae3f9b03303",
            "id": "r006-89b05e9a-e635-9464-9747-7ae3f9b03303",
            "name": "my-boot-volume",
            "resource_type": "volume"
          }
        },
        {
          "bandwidth": 250,
          "created_at": "2019-03-15T11:44:07.000Z",
          "delete_volume_on_instance_delete": false,
          "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
          "name": "my-data-volume-attachment",
          "status": "attached",
          "type": "data",
          "volume": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
            "name": "my-volume",
            "resource_type": "volume"
          }
        }
      ]
    }

Retrieve a volume attachment

This request retrieves a volume attachment for the calling instance.

GET /metadata/v1/instance/volume_attachments/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-volume-attachment.read

Request

Path Parameters

  • The volume attachment identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The volume attachment was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A volume attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "bandwidth": 250,
      "created_at": "2019-03-15T11:44:07.000Z",
      "delete_volume_on_instance_delete": false,
      "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a",
      "name": "my-data-volume-attachment",
      "status": "attached",
      "type": "data",
      "volume": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
        "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5",
        "name": "my-volume",
        "resource_type": "volume"
      }
    }

List public SSH keys

This request lists public SSH keys

GET /metadata/v1/keys

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-key.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The keys were retrieved successfully

Example responses
  • {
      "keys": [
        {
          "created_at": "2019-01-29T03:48:11.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
          "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
          "length": 2048,
          "name": "my-key-1",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "type": "rsa"
        },
        {
          "created_at": "2024-10-01T21:46:21.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468",
          "fingerprint": "SHA256:XgUFJWiZbPehNHl706+mJbZdPDmSJh8G2ycvCYR2t5U",
          "id": "r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468",
          "length": 2048,
          "name": "my-key-2",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6iw94c1htpVzC33sd874W6SeTZ9pGDZdY50vsnPUpYVfuU9WDscyy/NYVR74ZvSw1vN1QK57GEW46Uhh2JdvyQ1jiMPI6amu6bHiBqnWTo3HUFPBoxM9/3j0MhspjGyrO7JK3fOwyGrnquAqRq5BPibN8JLuZwCfVyucz98hEmnf9sEphJ5ab3ywVU3echaJZBEdUNEf2ZAHGGe5qnVW33y4PmRf5q90mPkJYwjTgTjZ3fPG2lV01S3eTbHV7zr1wxW4FSTFm7dVnfTURPzKc7mL4MS35s9gX73imvZL6O9ZH54IDoB8TBhx0U5657n6MoznFeXVcFSDLLpMXf7Gr",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "type": "rsa"
        }
      ]
    }

Retrieve a public SSH key

This request retrieves a public SSH key

GET /metadata/v1/keys/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-key.read

Request

Path Parameters

  • The key identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The key was retrieved successfully

  • A key with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2019-01-29T03:48:11.000Z",
      "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
      "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
      "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45",
      "length": 2048,
      "name": "my-key-1",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "type": "rsa"
    }

List placement groups

This request lists placement groups.

GET /metadata/v1/placement_groups

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-placement-group.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The placement groups were retrieved successfully

Example responses
  • {
      "placement_groups": [
        {
          "created_at": "2020-12-29T19:55:00.000Z",
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
          "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
          "lifecycle_state": "stable",
          "name": "my-placement-group",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "placement_group",
          "strategy": "host_spread"
        }
      ]
    }

Retrieve a placement group

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

GET /metadata/v1/placement_groups/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-placement-group.read

Request

Path Parameters

  • The placement group identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The placement group was retrieved successfully

  • An invalid authentication token was provided

  • The provided token is not authorized for this operation

  • A placement group with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "created_at": "2020-12-29T19:55:00.000Z",
      "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "lifecycle_state": "stable",
      "name": "my-placement-group",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "placement_group",
      "strategy": "host_spread"
    }

List virtual network interfaces

This request lists virtual network interfaces targeting the calling instance

GET /metadata/v1/virtual_network_interfaces

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-virtual-network-interface.list

Request

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The virtual network interfaces were retrieved successfully

Example responses
  • {
      "virtual_network_interfaces": [
        {
          "allow_ip_spoofing": false,
          "auto_delete": true,
          "created_at": "2024-10-15T03:24:32.993Z",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "enable_infrastructure_nat": false,
          "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
          "ips": [
            {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip",
              "resource_type": "subnet_reserved_ip"
            }
          ],
          "lifecycle_state": "stable",
          "mac_address": "02:00:04:00:C4:6A",
          "name": "my-virtual-network-interface",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip",
            "resource_type": "subnet_reserved_ip"
          },
          "protocol_state_filtering_mode": "auto",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "virtual_network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "target": {
            "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20",
            "name": "my-instance-network-attachment",
            "resource_type": "instance_network_attachment"
          },
          "vpc": {
            "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "name": "my-vpc",
            "resource_type": "vpc"
          },
          "zone": {
            "name": "us-south-1"
          }
        },
        {
          "allow_ip_spoofing": false,
          "auto_delete": true,
          "created_at": "2024-10-23T03:23:32.993Z",
          "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
          "enable_infrastructure_nat": false,
          "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9",
          "ips": [
            {
              "address": "10.0.1.5",
              "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
              "name": "my-reserved-ip",
              "resource_type": "subnet_reserved_ip"
            },
            {
              "address": "10.0.2.10",
              "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749",
              "name": "my-reserved-ip-2",
              "resource_type": "subnet_reserved_ip"
            }
          ],
          "lifecycle_state": "stable",
          "mac_address": "02:00:04:00:C4:6B",
          "name": "my-virtual-network-interface-2",
          "primary_ip": {
            "address": "10.0.1.5",
            "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
            "name": "my-reserved-ip",
            "resource_type": "subnet_reserved_ip"
          },
          "protocol_state_filtering_mode": "auto",
          "resource_group": {
            "id": "fee82deba12e4c0fb69c3b09d1f12345",
            "name": "Default"
          },
          "resource_type": "virtual_network_interface",
          "security_groups": [
            {
              "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
              "name": "my-security-group"
            }
          ],
          "subnet": {
            "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840",
            "ipv4_cidr_block": "10.0.2.0/24",
            "name": "my-subnet-2",
            "resource_type": "subnet"
          },
          "target": {
            "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20",
            "name": "my-instance-network-attachment",
            "resource_type": "instance_network_attachment"
          },
          "vpc": {
            "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
            "name": "my-vpc",
            "resource_type": "vpc"
          },
          "zone": {
            "name": "us-south-1"
          }
        }
      ]
    }

Retrieve a virtual network interface

This request retrieves a virtual network interface targeting the calling instance.

GET /metadata/v1/virtual_network_interfaces/{id}

Auditing

Calling this method generates the following auditing event.

  • is.metadata.instance-virtual-network-interface.read

Request

Path Parameters

  • The virtual network interface identifier

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2024-10-22 and 2024-11-05.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-06-23

  • The API maturity. For the API behavior documented here, specify beta.

    Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-z][a-z0-9]*(_[a-z0-9]+)*$

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"

Response

Status Code

  • The virtual network interface was retrieved successfully

  • A virtual network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses
  • {
      "allow_ip_spoofing": false,
      "auto_delete": true,
      "created_at": "2024-10-15T03:24:32.993Z",
      "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
      "enable_infrastructure_nat": false,
      "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef",
      "ips": [
        {
          "address": "10.0.1.5",
          "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
          "name": "my-reserved-ip",
          "resource_type": "subnet_reserved_ip"
        }
      ],
      "lifecycle_state": "stable",
      "mac_address": "02:00:04:00:C4:6A",
      "name": "my-virtual-network-interface",
      "primary_ip": {
        "address": "10.0.1.5",
        "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb",
        "name": "my-reserved-ip",
        "resource_type": "subnet_reserved_ip"
      },
      "protocol_state_filtering_mode": "auto",
      "resource_group": {
        "id": "fee82deba12e4c0fb69c3b09d1f12345",
        "name": "Default"
      },
      "resource_type": "virtual_network_interface",
      "security_groups": [
        {
          "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271",
          "name": "my-security-group"
        }
      ],
      "subnet": {
        "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "target": {
        "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20",
        "name": "my-instance-network-attachment",
        "resource_type": "instance_network_attachment"
      },
      "vpc": {
        "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b",
        "name": "my-vpc",
        "resource_type": "vpc"
      },
      "zone": {
        "name": "us-south-1"
      }
    }
id=curlclassName=tab-item-selected