IBM Cloud API Docs

Introduction to the beta VPC instance metadata API

Last updated: 2024-04-23

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

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

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

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

Request Body

InstanceIdentityIAMTokenPrototype

The IAM access token prototype.

Example request

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

Response

Response Body

InstanceIdentityIAMToken

Information about this instance identity IAM access token

Status Code

200
The IAM access token was successfully generated.
400
An invalid access token prototype object was provided.
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
  "created_at": "2021-03-22T14:10:15Z",
  "expires_at": "2021-03-22T15:10:15Z",
  "expires_in": 3600
}

Status 400

{
  "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"
}

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

Metadata-Flavor
Required*
string
The metadata flavor. Currently, only ibm is supported.

Allowable values: [ibm]

Query Parameters

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

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

Request Body

Required*

InstanceIdentityTokenPrototype

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

Example request

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

Response

Response Body

InstanceIdentityToken

Information about this access token

Status Code

200
The access token was created successfully.
400
An invalid access token prototype object was provided.

Example responses

Status 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6IkVyaWNhIn0.c4C_BKtyZ4g78TB6wjdsX_MNx4KPoYj8YiikB1jO4o8",
  "created_at": "2021-03-22T15:09:45Z",
  "expires_at": "2021-03-22T15:10:15Z",
  "expires_in": 30
}

Status 400

{
  "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"
}

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

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

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

Request Body

Required*

InstanceIdentityCertificatePrototype

The instance identity certificate prototype

Example request

curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/certificates?version=2024-04-23&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

Response Body

InstanceIdentityCertificate

Information about this instance identity certificate

Status Code

201
The instance identity certificate was created successfully.
400
An invalid instance identity certificate prototype object was provided.
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 201

{
  "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"
}

Status 400

{
  "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"
}

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

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

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

Example request

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

Response

Response Body

Instance

Status Code

200
The instance was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "availability_policy": {
    "host_failure": "restart"
  },
  "bandwidth": 4000,
  "boot_volume_attachment": {
    "device": {
      "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8"
    },
    "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"
    }
  },
  "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": [],
  "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-network-attachment",
      "primary_ip": {
        "address": "10.240.0.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"
      }
    }
  ],
  "network_interfaces": [
    {
      "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e",
      "name": "my-instance-network-interface",
      "primary_ipv4_address": "10.240.0.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-network-attachment",
    "primary_ip": {
      "address": "10.240.0.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"
    }
  },
  "primary_network_interface": {
    "id": "0717-10c02d81-0ecb-4dc5-897d-28392913b81e",
    "name": "my-instance-network-interface",
    "primary_ipv4_address": "10.240.0.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-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8"
      },
      "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"
  }
}

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

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

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

Example request

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

Response

Response Body

InstanceInitialization

Status Code

200
The initialization information was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "default_trusted_profile": {
    "auto_link": true,
    "target": {
      "crn": "crn:[...]",
      "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5",
      "resource_type": "trusted_profile"
    }
  },
  "keys": [
    {
      "crn": "crn:[...]",
      "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
      "id": "82679077-ac3b-4c10-be16-63e9c21f0f45",
      "name": "my-key-1"
    }
  ],
  "user_data": "[...]"
}

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

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

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

Example request

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

Response

Response Body

InstanceNetworkAttachmentCollection

Status Code

200
The instance network attachments were retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "network_attachments": [
    {
      "created_at": "2023-09-30T23:42:32.993Z",
      "id": "2be851a6-930e-4724-980d-f03e31b00295",
      "lifecycle_state": "stable",
      "name": "my-instance-network-attachment",
      "port_speed": 1000,
      "primary_ip": {
        "address": "10.0.0.5",
        "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d",
        "name": "my-reserved-ip-1",
        "resource_type": "subnet_reserved_ip"
      },
      "resource_type": "instance_network_attachment",
      "subnet": {
        "crn": "crn:[...]",
        "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary",
      "virtual_network_interface": {
        "crn": "crn:[...]",
        "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef",
        "name": "my-virtual-network-interface",
        "resource_type": "virtual_network_interface"
      }
    },
    {
      "created_at": "2023-09-30T23:42:33.366Z",
      "id": "822a3789-61d5-4b8e-82c5-4310e6b7dc1b",
      "lifecycle_state": "stable",
      "name": "my-instance-network-attachment-2",
      "port_speed": 1000,
      "primary_ip": {
        "address": "10.1.0.5",
        "id": "8d95aae7-04a2-4418-b54d-5a61d74856da",
        "name": "my-reserved-ip-2",
        "resource_type": "subnet_reserved_ip"
      },
      "resource_type": "instance_network_attachment",
      "subnet": {
        "crn": "crn:[...]",
        "id": "2302-822a3789-61d5-4b8e-82c5-4310e6b7dc1b",
        "name": "my-subnet-2",
        "resource_type": "subnet"
      },
      "type": "secondary",
      "virtual_network_interface": {
        "crn": "crn:[...]",
        "id": "0767-a36aa161-271a-4ea2-825c-0e1216e1035e",
        "name": "my-virtual-network-interface-2",
        "resource_type": "virtual_network_interface"
      }
    }
  ]
}

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

id
Required*
string
The instance network attachment identifier

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

Query Parameters

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

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

Example request

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

Response

Response Body

InstanceNetworkAttachment

Status Code

200
The instance network attachment was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation
404
A network attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "created_at": "2023-09-30T23:42:32.993Z",
  "id": "2be851a6-930e-4724-980d-f03e31b00295",
  "lifecycle_state": "stable",
  "name": "my-instance-network-attachment",
  "port_speed": 1000,
  "primary_ip": {
    "address": "10.0.0.5",
    "id": "5e2c7f65-6393-4345-a5b7-3d13242ae68d",
    "name": "my-reserved-ip-1",
    "resource_type": "subnet_reserved_ip"
  },
  "resource_type": "instance_network_attachment",
  "subnet": {
    "crn": "crn:[...]",
    "id": "2302-ea5fe79f-52c3-4f05-86ae-9540a10489f5",
    "name": "my-subnet",
    "resource_type": "subnet"
  },
  "type": "primary",
  "virtual_network_interface": {
    "crn": "crn:[...]",
    "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef",
    "name": "my-virtual-network-interface",
    "resource_type": "virtual_network_interface"
  }
}

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

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

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

Example request

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

Response

Response Body

NetworkInterfaceUnpaginatedCollection

Status Code

200
The instance network interfaces were retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "network_interfaces": [
    {
      "allow_ip_spoofing": false,
      "created_at": "2019-01-31T03:42:32.993Z",
      "floating_ips": [
        {
          "address": "192.0.2.2",
          "crn": "crn:[...]",
          "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1",
          "name": "my-floating-ip"
        }
      ],
      "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20",
      "name": "molecule-find-wild-name-dictionary-trench",
      "port_speed": 1000,
      "primary_ipv4_address": "10.0.0.32",
      "resource_type": "network_interface",
      "security_groups": [
        {
          "crn": "crn:[...]",
          "id": "a929f12d-fb45-4e5e-9864-95e171ae3589",
          "name": "before-entrance-mountain-paralegal-photo-uninstall"
        }
      ],
      "status": "available",
      "subnet": {
        "crn": "crn:[...]",
        "id": "9270d819-c05e-4352-99e4-80c4680cdb7c",
        "name": "my-subnet",
        "resource_type": "subnet"
      },
      "type": "primary"
    }
  ]
}

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

id
Required*
string
The instance network interface identifier

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

Query Parameters

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

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

Example request

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

Response

Response Body

NetworkInterface

Status Code

200
The instance network interface was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation
404
An instance network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "allow_ip_spoofing": false,
  "created_at": "2019-01-31T03:42:32.993Z",
  "floating_ips": [
    {
      "address": "192.0.2.2",
      "crn": "crn:[...]",
      "id": "181b8670-52bf-47af-a5ca-7aff7f3824d1",
      "name": "my-floating-ip"
    }
  ],
  "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20",
  "name": "molecule-find-wild-name-dictionary-trench",
  "port_speed": 1000,
  "primary_ipv4_address": "10.0.0.32",
  "resource_type": "network_interface",
  "security_groups": [
    {
      "crn": "crn:[...]",
      "id": "a929f12d-fb45-4e5e-9864-95e171ae3589",
      "name": "before-entrance-mountain-paralegal-photo-uninstall"
    }
  ],
  "status": "available",
  "subnet": {
    "crn": "crn:[...]",
    "id": "9270d819-c05e-4352-99e4-80c4680cdb7c",
    "name": "my-subnet",
    "resource_type": "subnet"
  },
  "type": "primary"
}

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

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

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

Example request

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

Response

Response Body

VolumeAttachmentCollection

Status Code

200
The volume attachments were retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation

Example responses

Status 200

{
  "volume_attachments": [
    {
      "bandwidth": 250,
      "created_at": "2019-02-28T16:32:05.000Z",
      "delete_volume_on_instance_delete": false,
      "id": "fdb3642d-c849-4c29-97a9-03b868616f88",
      "name": "my-boot-volume-attachment",
      "status": "attached",
      "type": "boot",
      "volume": {
        "crn": "crn:[...]",
        "id": "ac0b16a5-ccc2-47dd-90e2-b9e5f367b6c6",
        "name": "my-boot-volume",
        "resource_type": "volume"
      }
    },
    {
      "bandwidth": 250,
      "created_at": "2019-03-15T11:44:07.000Z",
      "delete_volume_on_instance_delete": false,
      "id": "8479a541-58ee-42ca-9efa-15a1551d42b9",
      "name": "my-data-volume-attachment",
      "status": "attached",
      "type": "data",
      "volume": {
        "crn": "crn:[...]",
        "id": "ca4b6df3-f5a8-4667-b5f2-f3b9b4160781",
        "name": "my-data-volume",
        "resource_type": "volume"
      }
    }
  ]
}

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

id
Required*
string
The volume attachment identifier

Query Parameters

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

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

Example request

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

Response

Response Body

VolumeAttachment

Status Code

200
The volume attachment was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation
404
A volume attachment with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "bandwidth": 250,
  "created_at": "2019-03-15T11:44:07.000Z",
  "delete_volume_on_instance_delete": false,
  "id": "8479a541-58ee-42ca-9efa-15a1551d42b9",
  "name": "my-data-volume-attachment",
  "status": "attached",
  "type": "data",
  "volume": {
    "crn": "crn:[...]",
    "id": "ca4b6df3-f5a8-4667-b5f2-f3b9b4160781",
    "name": "my-data-volume",
    "resource_type": "volume"
  }
}

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

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

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

Example request

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

Response

Response Body

KeyCollection

Status Code

200
The keys were retrieved successfully

Example responses

Status 200

{
  "keys": [
    {
      "created_at": "2019-01-29T03:48:11.000Z",
      "crn": "crn:[...]",
      "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
      "id": "82679077-ac3b-4c10-be16-63e9c21f0f45",
      "length": 2048,
      "name": "my-key-1",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
      "resource_group": {
        "id": "3fad3f2204eb4998c3964d254ffcd771",
        "name": "Default"
      },
      "type": "rsa"
    },
    {
      "created_at": "2019-01-21T01:28:11.000Z",
      "crn": "crn:[...]",
      "fingerprint": "SHA256:XgUFJWiZbPehNHl706+mJbZdPDmSJh8G2ycvCYR2t5U",
      "id": "a9f3ae27-4769-43e3-b5a3-a2856fbad468",
      "length": 2048,
      "name": "my-key-2",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6iw94c1htpVzC33sd874W6SeTZ9pGDZdY50vsnPUpYVfuU9WDscyy/NYVR74ZvSw1vN1QK57GEW46Uhh2JdvyQ1jiMPI6amu6bHiBqnWTo3HUFPBoxM9/3j0MhspjGyrO7JK3fOwyGrnquAqRq5BPibN8JLuZwCfVyucz98hEmnf9sEphJ5ab3ywVU3echaJZBEdUNEf2ZAHGGe5qnVW33y4PmRf5q90mPkJYwjTgTjZ3fPG2lV01S3eTbHV7zr1wxW4FSTFm7dVnfTURPzKc7mL4MS35s9gX73imvZL6O9ZH54IDoB8TBhx0U5657n6MoznFeXVcFSDLLpMXf7Gr",
      "resource_group": {
        "id": "3fad3f2204eb4998c3964d254ffcd771",
        "name": "Default"
      },
      "type": "rsa"
    }
  ]
}

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

id
Required*
string
The key identifier

Query Parameters

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

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

Example request

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

Response

Response Body

Key

Status Code

200
The key was retrieved successfully
404
A key with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "created_at": "2019-01-29T03:48:11.000Z",
  "crn": "crn:[...]",
  "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E",
  "id": "82679077-ac3b-4c10-be16-63e9c21f0f45",
  "length": 2048,
  "name": "my-key-1",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En",
  "resource_group": {
    "id": "3fad3f2204eb4998c3964d254ffcd771",
    "name": "Default"
  },
  "type": "rsa"
}

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

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

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

Example request

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

Response

Response Body

PlacementGroupCollection

Status Code

200
The placement groups were retrieved successfully

Example responses

Status 200

{
  "placement_groups": [
    {
      "created_at": "2020-12-29T19:55:00Z",
      "crn": "crn:[...]",
      "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "lifecycle_state": "stable",
      "name": "my-updated-placement-group",
      "resource_group": {
        "id": "4bbce614c13444cd8fc5e7e878ef8e21",
        "name": "Default"
      },
      "resource_type": "placement_group",
      "strategy": "host_spread"
    }
  ]
}

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

id
Required*
string
The placement group identifier

Query Parameters

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

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

Example request

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

Response

Response Body

PlacementGroup

Status Code

200
The placement group was retrieved successfully
401
An invalid authentication token was provided
403
The provided token is not authorized for this operation
404
A placement group with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "created_at": "2020-12-29T19:55:00.000Z",
  "crn": "crn:[...]",
  "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871",
  "lifecycle_state": "stable",
  "name": "my-placement-group",
  "resource_group": {
    "id": "4bbce614c13444cd8fc5e7e878ef8e21",
    "name": "Default"
  },
  "resource_type": "placement_group",
  "strategy": "host_spread"
}

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

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

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

Example request

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

Response

Response Body

VirtualNetworkInterfaceCollection

Status Code

200
The virtual network interfaces were retrieved successfully

Example responses

Status 200

{
  "virtual_network_interfaces": [
    {
      "allow_ip_spoofing": false,
      "auto_delete": true,
      "created_at": "2019-01-31T03:42:32.993Z",
      "crn": "crn:[...]",
      "enable_infrastructure_nat": false,
      "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef",
      "ips": [
        {
          "address": "10.0.0.32",
          "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5",
          "name": "my-reserved-ip-1",
          "resource_type": "subnet_reserved_ip"
        }
      ],
      "lifecycle_state": "stable",
      "mac_address": "02:00:04:00:C4:6A",
      "name": "my-virtual-network-interface",
      "primary_ip": {
        "address": "10.0.0.32",
        "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5",
        "name": "my-reserved-ip-1",
        "resource_type": "subnet_reserved_ip"
      },
      "resource_group": {
        "id": "4bbce614c13444cd8fc5e7e878ef8e21",
        "name": "Default"
      },
      "resource_type": "virtual_network_interface",
      "security_groups": [
        {
          "crn": "crn:[...]",
          "id": "a929f12d-fb45-4e5e-9864-95e171ae3589",
          "name": "my-security-group"
        }
      ],
      "subnet": {
        "crn": "crn:[...]",
        "id": "9270d819-c05e-4352-99e4-80c4680cdb7c",
        "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:[...]",
        "id": "a0819609-0997-4f92-9409-86c95ddf59d3",
        "name": "my-vpc",
        "resource_type": "vpc"
      },
      "zone": {
        "name": "us-south-1"
      }
    }
  ]
}

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

id
Required*
string
The virtual network interface identifier

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

Query Parameters

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

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

Example request

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

Response

Response Body

VirtualNetworkInterface

Status Code

200
The virtual network interface was retrieved successfully
404
A virtual network interface with the specified identifier could not be found or is not associated with the calling instance

Example responses

Status 200

{
  "allow_ip_spoofing": false,
  "auto_delete": true,
  "created_at": "2019-01-31T03:42:32.993Z",
  "crn": "crn:[...]",
  "enable_infrastructure_nat": false,
  "id": "0767-54eb57ee-86f2-4796-90bb-d7874e0831ef",
  "ips": [
    {
      "address": "10.0.0.32",
      "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5",
      "name": "my-reserved-ip-1",
      "resource_type": "subnet_reserved_ip"
    }
  ],
  "lifecycle_state": "stable",
  "mac_address": "02:00:04:00:C4:6A",
  "name": "my-virtual-network-interface",
  "primary_ip": {
    "address": "10.0.0.32",
    "id": "0716-7768a27e-cd6c-4a13-a9e6-d67a964e54a5",
    "name": "my-reserved-ip-1",
    "resource_type": "subnet_reserved_ip"
  },
  "resource_group": {
    "id": "4bbce614c13444cd8fc5e7e878ef8e21",
    "name": "Default"
  },
  "resource_type": "virtual_network_interface",
  "security_groups": [
    {
      "crn": "crn:[...]",
      "id": "a929f12d-fb45-4e5e-9864-95e171ae3589",
      "name": "my-security-group"
    }
  ],
  "subnet": {
    "crn": "crn:[...]",
    "id": "9270d819-c05e-4352-99e4-80c4680cdb7c",
    "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:[...]",
    "id": "a0819609-0997-4f92-9409-86c95ddf59d3",
    "name": "my-vpc",
    "resource_type": "vpc"
  },
  "zone": {
    "name": "us-south-1"
  }
}

Introduction to the beta VPC instance metadata API

Versioning

Maturity query parameter

Change log

Related APIs

Methods

Create an IAM token using an instance identity token

Auditing

Request

Query Parameters

version

Request Body

trusted_profile

Response

Response Body

access_token

created_at

expires_at

expires_in

Status Code

200

400

401

403

Create an instance identity access token

Auditing

Request

Custom Headers

Metadata-Flavor

Query Parameters

version

Request Body

expires_in

Response

Response Body

access_token

created_at

expires_at

expires_in

Status Code

200

400

Create an instance identity certificate using an instance identity access token

Auditing

Request

Query Parameters

version

Request Body

csr

expires_in

Response

Response Body

certificates

created_at

expires_at

expires_in

id

Status Code

201

400

401

403

Retrieve the instance

Auditing

Request

Query Parameters

version

Response

Response Body

availability_policy

host_failure

bandwidth

boot_volume_attachment

id

name

deleted

more_info

device

id

volume