IBM Cloud API Docs

Introduction

The IBM Cloud® Virtual Private Cloud (VPC) Instance Metadata API provides access to VPC instance metadata, including:

  • Instance initialization data
  • Network interfaces
  • Volume attachments
  • Public SSH keys
  • Placement groups

Access to API services is made available from within the instance itself and is inaccessible from outside the instance. Metadata provided by API services pertains only to the instance from which the request is made. It is not possible to use instance metadata API services within an instance to obtain information about another instance or to obtain information about resources not currently associated with the instance.

Optionally, if an IBM Cloud Identity and Access Management (IAM) trusted profile is used to establish a trust relationship with the instance, the Instance Metadata API provides the ability for the instance to get access tokens for other IAM-enabled cloud services, such as API Connect, Blockchain Platform, Event Streams, Secrets Manager, and Cloud Object Storage.

Endpoint URLs

By default, instances are created with the metadata service endpoint disabled. You can enable the metadata service either when creating a VPC instance or by updating the VPC instance after creation.

The Instance Metadata API can be accessed from within that instance using an endpoint URL:

  • When the metadata_service.protocol property is http, the endpoint URL may contain either the service's IP address http://169.254.169.254 or the service's hostname http://api.metadata.cloud.ibm.com.
  • When the metadata_service.protocol property is https, the endpoint URL must contain the service's hostname https://api.metadata.cloud.ibm.com.

You cannot configure the metadata service with both http and https protocols at the same time.

When the metadata_service.enabled property is false, the Instance Metadata API will not be available. Requests sent to any of the endpoint URLs will not receive a response.

This example stores the metadata service's hostname api.metadata.cloud.ibm.com in a vpc_metadata_api_endpoint variable.

vpc_metadata_api_endpoint=http://api.metadata.cloud.ibm.com

Authentication

To start a metadata session with the Instance Metadata API, obtain an instance identity access token with the Create an access token for VPC metadata method. You can also generate an IAM token from this token by making a POST /instance_identity/v1/iam_token call, as shown in the second example.

A session lasts for the lifetime of the token, during which the metadata service can be called. You can reuse a single access token for multiple metadata API calls, as long as the token has not expired.

The examples use jq as a parser, a third-party tool licensed under the MIT license. jq may not come preinstalled on all VPC images available when creating an instance. You might need to install jq prior to use or use any parser of your choice.

Consider storing the metadata endpoint in a variable. Use the example on this page or see Configure the instance metadata service for more information.

This example extracts the access token value and places it in the instance_identity_token environment variable.

instance_identity_token=`curl -X PUT   "$vpc_metadata_api_endpoint/instance_identity/v1/token?version=2024-03-26"   -H "Metadata-Flavor: ibm"   -H "Accept: application/json"   -d '{           "expires_in": 300       }' | jq -r '(.access_token)'`

Example response from the previous request:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5MmI0YzAxNWJhOTc4NzgiLCJ....",
  "created_at": "2024-03-19T11:08:39.363Z",
  "expires_at": "2024-03-19T11:13:39.363Z",
  "expires_in": 300
}

Pass the access token in the Authorization header to authenticate metadata requests. Tokens authenticate requests without embedding service credentials in every call. See the methods in the API specification for examples using $instance_identity_token.

This example uses the instance_identity_token environment variable from the previous example to create an IAM token associated with the specified trusted profile ID. Upon success, provide the iam_token environment variable when calling any IAM-enabled IBM service to perform operations using the authorizations granted to that trusted profile. Learn more about Creating trusted profiles.

iam_token=`curl -X POST   "$vpc_metadata_api_endpoint/instance_identity/v1/iam_token?version=2024-03-26"   -H "Authorization: Bearer $instance_identity_token"   -d '{
       "trusted_profile": {
          "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
       }
      }' | jq -r '(.access_token)'`

This example shows how to use the HTTPS protocol to retrieve instance initialization metadata. For this example, the service must be configured with the metadata_service.protocol property set to https.

user_data=`curl -X GET    "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-03-26"   -H "Accept: application/json"   -H "Authorization: Bearer $instance_identity_token"
  | jq -r '(.user_data)'`

Auditing

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

Error handling

As covered in Instance metadata API error codes, this API uses standard HTTP response codes to indicate the outcome of a request. A 2xx-series response indicates success. A 4xx-series response indicates a failure that the client must resolve. A 5xx-series response indicates a service failure.

HTTP error code Description Disposition
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to perform the requested operation.
404 Not Found The requested resource could not be found or is not associated with the calling instance.
408 Request Timeout The connection to the server timed out. Wait a few minutes, and try again.
500 Internal Server Error A generic error message is returned when an unexpected condition was encountered and no more specific message is suitable.
501 Not Implemented The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this message implies future availability, such as a new feature of a web-service API.
502 Bad Gateway The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition may also be due to an unplanned outage of a service that is needed to process the request.
504 Gateway Timeout The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
505 HTTP Version Not Supported The server does not support the HTTP protocol version that is used in the request.

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.

Use any date-based version, from 2022-03-01 up to the current date. Start development of new applications with the current date as a fixed value. Don't dynamically use the current date as the version for a production application. Instead, use a fixed date-based version that you tested with your application. Periodically check the change log for API changes. Update and test your application with new version dates to maintain ongoing compatibility.

This example includes date-based version as a query parameter and shows how to use the HTTPS protocol to retrieve instance initialization metadata. For this example, the service must be configured with the metadata_service.protocol property set to https.

user_data=`curl -X GET   "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-03-26"   -H "Authorization: Bearer $instance_identity_token"   | jq -r '(.user_data)'`

Response model properties

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

user_data=`curl -X GET \
  "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-03-26" \
  -H "Authorization: Bearer $instance_identity_token" \
  | jq -r '(.user_data)'`

VPC API resource conventions

See the following sections in the Virtual Private Cloud API to learn about resource naming and handling:

API best practices

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

  • Log any 4xx or 5xx HTTP status code along with the included trace property
  • Follow HTTP redirect rules for any 3xx HTTP status code
  • Use only the resources and properties that are needed for your application to function
  • Avoid depending on any behavior that is not explicitly documented

Change log

Review the change log for important changes to the VPC Instance Metadata API, such as additions, updates, and versioned changes.

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 2023-12-05 and 2024-03-26.

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

The IAM access token prototype.

  • curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/iam_token?version=2024-03-26" -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 2023-12-05 and 2024-03-26.

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

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-03-26" -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 2023-12-05 and 2024-03-26.

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

The instance identity certificate prototype

  • curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/certificates?version=2024-03-26" -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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2024-03-26" -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": "a8a15363-a6f7-4f01-af60-715e85b28141"
        },
        "id": "7389-a8a15363-a6f7-4f01-af60-715e85b28141",
        "name": "my-boot-volume-attachment",
        "volume": {
          "crn": "crn:[...]",
          "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
          "name": "my-boot-volume",
          "resource_type": "volume"
        }
      },
      "created_at": "2020-03-26T16:11:57Z",
      "crn": "crn:[...]",
      "dedicated_host": {
        "crn": "crn:[...]",
        "id": "0787-8c2a09be-ee18-4af2-8ef4-6a6060732221",
        "name": "test-new",
        "resource_type": "dedicated_host"
      },
      "disks": [],
      "health_reasons": [],
      "health_state": "ok",
      "id": "eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
      "image": {
        "crn": "crn:[...]",
        "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
        "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": "4cf9171a-0043-4434-8727-15b53dbc374c",
          "name": "my-network-attachment",
          "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_type": "instance_network_attachment",
          "subnet": {
            "crn": "crn:[...]",
            "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
            "name": "my-subnet",
            "resource_type": "subnet"
          },
          "type": "primary"
        }
      ],
      "network_interfaces": [
        {
          "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
          "name": "my-network-interface",
          "primary_ipv4_address": "10.0.0.32",
          "resource_type": "network_interface",
          "subnet": {
            "crn": "crn:[...]",
            "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
            "name": "my-subnet",
            "resource_type": "subnet"
          }
        }
      ],
      "numa_count": 2,
      "placement_target": {
        "crn": "crn:[...]",
        "id": "0787-84e4793a-7cd8-4a7b-b253-818aa19d0512",
        "name": "test-new",
        "resource_type": "dedicated_host"
      },
      "primary_network_attachment": {
        "id": "4cf9171a-0043-4434-8727-15b53dbc374c",
        "name": "my-network-attachment",
        "primary_ip": {
          "address": "10.0.0.32",
          "id": "0716-cbdf30f2-1632-46ed-bcf0-5ffb8ebc028a",
          "name": "my-reserved-ip-1",
          "resource_type": "subnet_reserved_ip"
        },
        "resource_type": "instance_network_attachment",
        "subnet": {
          "crn": "crn:[...]",
          "id": "7389-bea6a632-5e13-42a4-b4b8-31dc877abfe4",
          "name": "my-subnet",
          "resource_type": "subnet"
        }
      },
      "primary_network_interface": {
        "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
        "name": "my-network-interface",
        "primary_ipv4_address": "10.0.0.32",
        "resource_type": "network_interface",
        "subnet": {
          "crn": "crn:[...]",
          "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
          "name": "my-subnet",
          "resource_type": "subnet"
        }
      },
      "profile": {
        "name": "bx2-2x8",
        "resource_type": "instance_profile"
      },
      "reservation_affinity": {
        "policy": "disabled",
        "pool": []
      },
      "resource_group": {
        "id": "4bbce614c13444cd8fc5e7e878ef8e21",
        "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": "a8a15363-a6f7-4f01-af60-715e85b28141"
          },
          "id": "7389-a8a15363-a6f7-4f01-af60-715e85b28141",
          "name": "my-boot-volume-attachment",
          "volume": {
            "crn": "crn:[...]",
            "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
            "name": "my-boot-volume",
            "resource_type": "volume"
          }
        },
        {
          "device": {
            "id": "e77125cb-4df0-4988-a878-531ae0ae0b70"
          },
          "id": "7389-e77125cb-4df0-4988-a878-531ae0ae0b70",
          "name": "my-volume-attachment-1",
          "volume": {
            "crn": "crn:[...]",
            "id": "2cc091f5-4d46-48f3-99b7-3527ae3f4392",
            "name": "my-data-volume",
            "resource_type": "volume"
          }
        }
      ],
      "vpc": {
        "crn": "crn:[...]",
        "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f",
        "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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-03-26" -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:[...]",
          "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": "[...]"
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments?version=2024-03-26" -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": "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"
          }
        }
      ]
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments/$id?version=2024-03-26" -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": "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"
      }
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces?version=2024-03-26" -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": "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"
        }
      ]
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces/$id?version=2024-03-26" -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": "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"
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments?version=2024-03-26" -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": "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"
          }
        }
      ]
    }

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments/$id?version=2024-03-26" -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": "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"
      }
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys?version=2024-03-26" -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:[...]",
          "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"
        }
      ]
    }

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys/$id?version=2024-03-26" -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:[...]",
      "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"
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups?version=2024-03-26" -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: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"
        }
      ]
    }

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

Query Parameters

  • The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date between 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups/$id?version=2024-03-26" -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:[...]",
      "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"
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces?version=2024-03-26" -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": "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"
          }
        }
      ]
    }

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 2023-12-05 and 2024-03-26.

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

  • curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces/$id?version=2024-03-26" -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": "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"
      }
    }