Introduction to the beta VPC instance metadata API
This reference includes the full IBM Cloud® Virtual Private Cloud (VPC) Instance Metadata API, as well as newly released open beta features. This reference may also include limited beta features for customer accounts with special approval to preview those features.
There are no backward-compatibility guarantees as a feature progresses through its beta phase, or from the final beta release to its initial GA release. Using features that are not GA mature could introduce the risk of corrupting resources in your account.
Read the introduction in the generally available VPC Instance Metadata API for details on endpoint URLs, authentication, auditing, error handling, versioning, and other important information.
Versioning
API requests require a major version in the path (/v1/
) and a date-based version as a query
parameter in the format version=YYYY-MM-DD
.
This reference documents API behavior for any date value in the version
parameter within 45 days
of today’s date. To view the reference for any other supported versions of the API, select it from
the Version list. See also Versioning in the VPC API.
Maturity query parameter
API requests accept a maturity
query parameter. This parameter lets you decide on the level of
stability to use before features become generally available.
API requests must specify a maturity=beta
query parameter. Omitting maturity
results in the GA
version of the API being used, which can result in different behavior.
Example of using the maturity
parameter in a request:
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?maturity=beta" -H "Authorization: Bearer $iam_token"
Change log
Important changes to the beta metadata API, such as additions, updates, and deprecations, are documented in the Beta VPC Instance Metadata API change log.
Methods
Create an IAM token using an instance identity token
This request uses an instance identity access token, and a trusted profile linked to a virtual server instance (whether the default linked at instance creation time, or one provided in the request body) to generate an IAM access token.
POST /instance_identity/v1/iam_token
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The IAM access token prototype.
Identifies a trusted profile by a unique property.
curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/iam_token?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token" -d '{ "trusted_profile": { "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5" } }'
Response
Information about this instance identity IAM access token
The access token
Possible values: 14 ≤ length ≤ 2000, Value must match regular expression
^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50IjoiYWEyNDMyYjFmYTRkNGFjZTg5MWU5YjgwZmMxMDRlMzQiLCJzZWNyZXQiOiJRVzRnWlhoaGJYQnNaU0J6WldOeVpYUUsiLCJleHAiOjE3MjYwNzU1OTR9.UFDVzzGJ54Go9Z4jgyPSLG49zNx-AjHTQrJA6ee8KLI
The date and time that the access token was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2021-03-22T21:50:14Z
The date and time that the access token will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2021-03-22T21:51:14Z
Time in seconds before the access token expires
Possible values: 5 ≤ value ≤ 3600
Example:
60
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
{ "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
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 between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The access token prototype. A valid prototype object is required even if no properties are specified.
Time in seconds before the access token expires
Possible values: 5 ≤ value ≤ 3600
Default:
300
Example:
60
curl -X PUT "$vpc_metadata_api_endpoint/instance_identity/v1/token?version=2024-11-05&maturity=beta" -H "Metadata-Flavor: ibm" -d '{}'
Response
Information about this access token
The access token
Possible values: 14 ≤ length ≤ 2000, Value must match regular expression
^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50IjoiYWEyNDMyYjFmYTRkNGFjZTg5MWU5YjgwZmMxMDRlMzQiLCJzZWNyZXQiOiJRVzRnWlhoaGJYQnNaU0J6WldOeVpYUUsiLCJleHAiOjE3MjYwNzU1OTR9.UFDVzzGJ54Go9Z4jgyPSLG49zNx-AjHTQrJA6ee8KLI
The date and time that the access token was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2021-03-22T21:50:14Z
The date and time that the access token will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2021-03-22T21:51:14Z
Time in seconds before the access token expires
Possible values: 5 ≤ value ≤ 3600
Example:
60
Status Code
The access token was created successfully.
An invalid access token prototype object was provided.
{ "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
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The instance identity certificate prototype
A Public-Key Cryptography Standards (PKCS) #10 certification request provided in textual encoding described by RFC 7468.
Certificate signing requests (CSRs) must meet the following requirements:
- Version: v1 (value
0
) - Subject public key algorithm: 2048-bit or 4096-bit RSA
- Signature algorithm: SHA-256 with RSA encryption
- Attributes: empty (constructed DER encoding value
a0 00
) - Subject: At least one of the following naming attributes must be specified:
C
: The ISO 3166-1 alpha-2 country name (section 6.3.1 of X.520)L
: The locality name (section 6.3.4 of X.520)ST
: The full state or province name (section 6.3.5 of X.520)O
: The organization name (section 6.4.1 of X.520)OU
: The organizational unit name (section 6.4.2 of X.520)- No other naming attributes may be specified
See Generating an instance identity certificate by using an instance identity access token, ITU X.520 10/2019, RFC 5280, and RFC 2985 for more information.
Possible values: length ≥ 75, Value must match regular expression
^-----BEGIN CERTIFICATE REQUEST-----(\n|\r|\r\n)([0-9a-zA-Z\+\/=]{64}(\n|\r|\r\n))*([0-9a-zA-Z\+\/=]{1,63}(\n|\r|\r\n))?-----END CERTIFICATE REQUEST-----(\n|\r|\r\n)*$
Examples:-----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-----
- Version: v1 (value
Time in seconds before the instance identity certificate expires
Possible values: 300 ≤ value ≤ 3600
Default:
3600
Example:
1800
curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/certificates?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token" -d '{ "csr": | -----BEGIN CERTIFICATE REQUEST----- MIICzzCCAbcCAQAwgYkxCzAJBgNVBAYTAlVTMRIwEAYDVQQIDAlNaW5uZXNvdGEx EjAQBgNVBAcMCVJvY2hlc3RlcjEMMAoGA1UECgwDSUJNMR4wHAYDVQQLDBVWaXJ0 dWFsIFByaXZhdGUgQ2xvdWQxJDAiBgNVBAMMG1ZQQyBFeGFtcGxlIEludGVybWVk aWF0ZSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY78TrUhSrC SpeLXgS4JF+PpssYQpc9kJoOTJzUPqMocja6WL4xt/jvg60lCik185lkpClP+gSp h0DzXaXeMpm29HBu8JqXFN2I460jRYHf6NwhCvTO/qHyLkLU11zVEFl+a298AahA NU1ms1U2aaYYYXBkPLtN1Uyr6BeEtgyOi926wySdMNQzPSLGmgdpkuuFWDCI94y6 8t/a8hhKGKtWtLQuAvXxE91eTZlJyETalQ5xhpGAcv+e1UQAlF8V3ELlunqD2BpO h6N3ipct+HopRdp/cQ/2weNUeDc2sTv9JR6vnGiOa9VpZ017RRPMC6RaGDJLgtKo igXrMrsnn9kCAwEAAaAAMA0GCSqGSIb3DQEBCwUAA4IBAQBCb71iIsm+ak94qO2+ n7+WYLkIPCyIDb5mBCqJi5AL1ZC+WqbNVf4NqC6zS9qJbeQGOId5sGVLkdJjcccg f6SrE0mrC1h43ttwkZGNWML+rO0OlEuEDYdfsUQuH24t9KQNf2c6pmdLdchNovFz blhmHdjcUUAVYHHrFPgT0uvQVYEFLLIGa2ZHVeTJvZf4IVW2SiezSt/d6NsHi3s1 rVZ8UIXXaFsOkgF65+D14hW+t9GzajSYY/IlU4E5YCRO9lHM/YmlbQRNXJgHDMta /uh2hhK3mMR7sfeBhHYvqs1hxBaLEka5rKOO61q8Px9eCC+WZx2nyHFILp86RyT0 mL9R -----END CERTIFICATE REQUEST----- }'
Response
Information about this instance identity certificate
The public key certificates, consisting of the instance identity certificate, and all intermediate CA certificates in its chain of trust. Certificates are based upon the X.509 v3 certificate format and the standard certificate extensions defined in RFC 5280.
The certificates are issued by an IBM Cloud Virtual Private Cloud (VPC) certification authority (CA). VPC provides the public key infrastructure (PKI) establishing a chain of trust for use with VPC file share services.
All certificates are provided in textual encoding described by RFC 7468.
Possible values: 1 ≤ number of items ≤ 10, contains only unique items, Value must match regular expression
^-----BEGIN CERTIFICATE-----(\n|\r|\r\n)([0-9a-zA-Z\+\/=]{64}(\n|\r|\r\n))*([0-9a-zA-Z\+\/=]{1,63}(\n|\r|\r\n))?-----END CERTIFICATE-----(\n|\r|\r\n)+$
The date and time that the instance identity certificate was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2022-11-01T13:50:14Z
The date and time that the instance identity certificate will expire
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Example:
2022-11-01T14:20:14Z
Time in seconds before the instance identity certificate expires
Possible values: 300 ≤ value ≤ 3600
Example:
1800
The unique identifier for this instance identity certificate
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
9fd84246-7df4-4667-94e4-8ecde51d5ac5
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
{ "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
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The availability policy for this virtual server instance
- availability_policy
The action to perform if the compute host experiences a failure:
restart
: Automatically restart the virtual server instance after host failurestop
: Leave the virtual server instance stopped after host failure
The enumerated values for this property may expand in the future.
Possible values: [
restart
,stop
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The total bandwidth (in megabits per second) shared across the instance network attachments or instance network interfaces and storage volumes of the virtual server instance
Example:
1000
Boot volume attachment
Examples:{ "device": { "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb" }, "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }
- boot_volume_attachment
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.Examples:{ "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb" }
- device
A unique identifier for the device which is exposed to the instance operating system
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:{ "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" }
- volume
The CRN for this volume
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The confidential compute mode for this virtual server instance.
Possible values: [
disabled
,sgx
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The date and time that the virtual server instance was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The CRN for this virtual server instance
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0
The instance disks for this virtual server instance.
Possible values: number of items ≥ 0
Indicates whether secure boot is enabled for this virtual server instance.
The reasons for the current
health_state
(if any).Possible values: number of items ≥ 0
The health of this resource:
ok
: No abnormal behavior detecteddegraded
: Experiencing compromised performance, capacity, or connectivityfaulted
: Completely unreachable, inoperative, or otherwise entirely incapacitatedinapplicable
: The health state does not apply because of the current lifecycle state. A resource with a lifecycle state offailed
ordeleting
will have a health state ofinapplicable
. Apending
resource may also have this state.
Possible values: [
degraded
,faulted
,inapplicable
,ok
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
ok
The unique identifier for this virtual server instance
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0
The reasons for the current
lifecycle_state
(if any).Possible values: number of items ≥ 0
The lifecycle state of the virtual server instance.
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
stable
The amount of memory, truncated to whole gibibytes.
The maximum limit for this property may expand in the future.
Possible values: 1 ≤ value ≤ 256000
Example:
64
The metadata service configuration
The name for this virtual server instance. The name is unique across all virtual server instances in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance
The network attachments for this virtual server instance, including the primary network attachment.
Possible values: number of items ≥ 0, contains only unique items
The network interfaces for this instance, including the primary network interface.
If this instance has network attachments, each network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface.
Possible values: number of items ≥ 1, contains only unique items
The number of NUMA nodes this virtual server instance is provisioned on.
Possible values: value ≥ 1
Example:
2
The primary network interface for this virtual server instance.
If this instance has network attachments, this primary network interface is a read-only representation of the primary network attachment and its attached virtual network interface.
Examples:{ "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-interface", "primary_ipv4_address": "10.0.1.5", "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }
- primary_network_interface
The unique identifier for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the identifier is that of the corresponding network attachment.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network interface.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The primary IPv4 address.
If the address has not yet been selected, the value will be
0.0.0.0
.Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The associated subnet
Examples:{ "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" }
- subnet
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The profile for this virtual server instance
Examples:{ "name": "bx2-4x16", "resource_type": "instance_profile" }
- profile
The globally unique name for this virtual server instance profile
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
bx2-4x16
The resource type
Possible values: [
instance_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The resource group for this instance
Examples:{ "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }
- resource_group
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
The resource type
Possible values: [
instance
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Indicates whether the state of the virtual server instance permits a start request.
The status of the virtual server instance.
The enumerated values for this property may expand in the future.
Possible values: [
deleting
,failed
,pending
,restarting
,running
,starting
,stopped
,stopping
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The reasons for the current status (if any).
Possible values: number of items ≥ 0
The amount of bandwidth (in megabits per second) allocated exclusively to instance network attachments or instance network interfaces.
Example:
500
The amount of bandwidth (in megabits per second) allocated exclusively to instance storage volumes. An increase in this value will result in a corresponding decrease to
total_network_bandwidth
.Example:
500
The virtual server instance VCPU configuration
The volume attachments for this virtual server instance, including the boot volume attachment.
Possible values: number of items ≥ 1, contains only unique items
The VPC this virtual server instance resides in
Examples:{ "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" }
- vpc
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The zone this virtual server instance resides in
Examples:{ "name": "us-south-1" }
- zone
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
If present, this virtual server instance was provisioned from a catalog.
- catalog_offering
The catalog offering version this virtual server instance was provisioned from.
The catalog offering version is not managed by the IBM VPC service, and may no longer exist, or may refer to a different image CRN than the
image.crn
for this virtual server instance. However, all images associated with a catalog offering version will have the same checksum, and therefore will have the same data.- version
The CRN for this version of a catalog offering
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:globalcatalog-collection:global:a/aa2432b1fa4d4ace891e9b80fc104e34:1082e7d2-5e2f-0a11-a3bc-f88a8e1931fc:version:00111601-0ec5-41ac-b142-96d1e64e6442/ec66bec2-6a33-42d6-9323-26dd4dc8875d
The billing plan used for the catalog offering version.
If absent, no billing plan is in use (free).
- plan
The CRN for this catalog offering version's billing plan
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:globalcatalog-collection:global:a/aa2432b1fa4d4ace891e9b80fc104e34:51c9e0db-2911-45a6-adb0-ac5332d27cf2:plan:sw.51c9e0db-2911-45a6-adb0-ac5332d27cf2.772c0dbe-aa62-482e-adbe-a3fc20101e0e
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
If present, the dedicated host this virtual server instance has been placed on.
Examples:{ "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" }
- dedicated_host
The CRN for this dedicated host
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The unique identifier for this dedicated host
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-1e09281b-f177-46fb-baf1-bc152b2e391a
The name for this dedicated host. The name is unique across all dedicated hosts in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host
The resource type
Possible values: [
dedicated_host
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The virtual server instance GPU configuration
The image the virtual server instance was provisioned from
Examples:{ "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" }
- image
The CRN for this image
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The unique identifier for this image
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8
The name for this image. The name is unique across all images in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-image
The resource type
Possible values: [
image
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
If present, this property indicates that the resource associated with this reference is remote and therefore may not be directly retrievable.
The placement restrictions for the virtual server instance
- placement_target
The CRN for this dedicated host group
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host-group:bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The unique identifier for this dedicated host group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
bcc5b834-1258-4b9c-c3b4-43bc9cf5cde0
The name for this dedicated host group. The name is unique across all dedicated host groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-host-group
The resource type
Possible values: [
dedicated_host_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The primary network attachment for this virtual server instance
Examples:{ "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-attachment", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }
- primary_network_attachment
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The primary IP address of the virtual network interface for the instance network attachment
Examples:{ "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }
- primary_ip
The IP address.
If the address has not yet been selected, the value will be
0.0.0.0
.This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:{ "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" }
- subnet
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The virtual network interface for this instance network attachment
Examples:{ "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }
- virtual_network_interface
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The reservation used by this virtual server instance.
If absent, no reservation is in use.
Examples:{ "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:0717-ba49df72-37b8-43ac-98da-f8e029de0e63", "id": "0717-ba49df72-37b8-43ac-98da-f8e029de0e63", "name": "my-reservation", "resource_type": "reservation" }
- reservation
The CRN for this reservation
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::reservation:0717-ba49df72-37b8-43ac-98da-f8e029de0e63
The unique identifier for this reservation
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-ba49df72-37b8-43ac-98da-f8e029de0e63
The name for this reservation. The name is unique across all reservations in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reservation
The resource type
Possible values: [
reservation
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
Status Code
The instance was retrieved successfully
An invalid authentication token was provided
The provided token is not authorized for this operation
{ "availability_policy": { "host_failure": "restart" }, "bandwidth": 4000, "boot_volume_attachment": { "device": { "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb" }, "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, "confidential_compute_mode": "sgx", "created_at": "2020-03-26T16:11:57Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::instance:0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "dedicated_host": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "disks": [], "enable_secure_boot": true, "health_reasons": [], "health_state": "ok", "id": "0717_e21b7391-2ca2-4ab5-84a8-b92157a633b0", "image": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::image:r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "id": "r006-72b27b5c-f4b0-48bb-b954-5becc7c1dcb8", "name": "my-image", "resource_type": "image" }, "lifecycle_reasons": [], "lifecycle_state": "stable", "memory": 8, "metadata_service": { "enabled": true, "protocol": "http", "response_hop_limit": 1 }, "name": "my-instance", "network_attachments": [ { "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-attachment", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } } ], "network_interfaces": [ { "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-interface", "primary_ipv4_address": "10.0.1.5", "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } } ], "numa_count": 2, "placement_target": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::dedicated-host:0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "id": "0717-1e09281b-f177-46fb-baf1-bc152b2e391a", "name": "my-dedicated-host", "resource_type": "dedicated_host" }, "primary_network_attachment": { "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-attachment", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }, "primary_network_interface": { "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-interface", "primary_ipv4_address": "10.0.1.5", "resource_type": "network_interface", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" } }, "profile": { "name": "bx2-4x16", "resource_type": "instance_profile" }, "reservation_affinity": { "policy": "disabled", "pool": [] }, "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "instance", "startable": true, "status": "running", "status_reasons": [], "total_network_bandwidth": 3000, "total_volume_bandwidth": 1000, "vcpu": { "architecture": "amd64", "count": 2, "manufacturer": "intel" }, "volume_attachments": [ { "device": { "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb" }, "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-volume-attachment", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }, { "device": { "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70-w8mw8" }, "id": "0717-e77125cb-4df0-4988-a878-531ae0ae0b70", "name": "my-volume-attachment-2", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "id": "r006-2cc091f5-4d46-48f3-99b7-3527ae3f4392", "name": "my-volume-2", "resource_type": "volume" } } ], "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "name": "us-south-1" } }
Retrieve initialization information
This request retrieves initialization information for the calling instance.
GET /metadata/v1/instance/initialization
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The public SSH keys used at instance initialization.
User data to be made available when setting up the virtual server instance
Possible values: 0 ≤ length ≤ 65535, Value must match regular expression
^[\s\S]*$
The default trusted profile configuration specified at virtual server instance creation. If absent, no default trusted profile was specified.
- default_trusted_profile
If set to
true
, the system created a link to the specifiedtarget
trusted profile during instance creation. Regardless of whether a link was created by the system or manually using the IAM Identity service, it will be automatically deleted when the instance is deleted.Example:
true
The default IAM trusted profile to use for this virtual server instance
Examples:{ "crn": "crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5", "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5", "resource_type": "trusted_profile" }
- target
The CRN for this trusted profile
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
The unique identifier for this trusted profile
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^Profile-[-0-9a-z_]+$
Example:
Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5
The resource type
Possible values: [
trusted_profile
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Status Code
The initialization information was retrieved successfully
An invalid authentication token was provided
The provided token is not authorized for this operation
{ "default_trusted_profile": { "auto_link": true, "target": { "crn": "crn:v1:bluemix:public:iam-identity::a/aa2432b1fa4d4ace891e9b80fc104e34::profile:Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5", "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5", "resource_type": "trusted_profile" } }, "keys": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "name": "my-key-1" } ], "user_data": "[...]" }
List network attachments
This request lists network attachments for the calling instance.
GET /metadata/v1/instance/network_attachments
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The network attachments for the instance
Status Code
The instance network attachments were retrieved successfully
An invalid authentication token was provided
The provided token is not authorized for this operation
{ "network_attachments": [ { "created_at": "2023-09-30T23:42:32.993Z", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }, { "created_at": "2023-09-30T23:42:33.366Z", "id": "0717-822a3789-61d5-4b8e-82c5-4310e6b7dc1b", "lifecycle_state": "stable", "name": "my-instance-network-attachment-2", "port_speed": 1000, "primary_ip": { "address": "10.0.2.10", "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840", "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840", "name": "my-subnet-2", "resource_type": "subnet" }, "type": "secondary", "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9", "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9", "name": "my-virtual-network-interface-2", "resource_type": "virtual_network_interface" } } ] }
Retrieve a network attachment
This request retrieves a network attachment for the calling instance.
GET /metadata/v1/instance/network_attachments/{id}
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 between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_attachments/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The date and time that the instance network attachment was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The lifecycle state of the instance network attachment
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
stable
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The port speed for this instance network attachment in Mbps
Example:
1000
The primary IP address of the virtual network interface for the instance network attachment
Examples:{ "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }
- primary_ip
The IP address.
If the address has not yet been selected, the value will be
0.0.0.0
.This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The subnet of the virtual network interface for the instance network attachment
Examples:{ "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" }
- subnet
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The instance network attachment type
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
The virtual network interface for this instance network attachment
Examples:{ "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" }
- virtual_network_interface
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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
{ "created_at": "2023-09-30T23:42:32.993Z", "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "lifecycle_state": "stable", "name": "my-instance-network-attachment", "port_speed": 1000, "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "resource_type": "instance_network_attachment", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary", "virtual_network_interface": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "name": "my-virtual-network-interface", "resource_type": "virtual_network_interface" } }
List instance network interfaces
This request lists network interfaces for the calling instance.
GET /metadata/v1/instance/network_interfaces
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The network interfaces for the instance
Status Code
The instance network interfaces were retrieved successfully
An invalid authentication token was provided
The provided token is not authorized for this operation
{ "network_interfaces": [ { "allow_ip_spoofing": false, "created_at": "2024-10-15T03:24:32.993Z", "floating_ips": [ { "address": "203.0.113.1", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd", "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd", "name": "my-floating-ip" } ], "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-interface", "port_speed": 1000, "primary_ipv4_address": "10.0.1.5", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "status": "available", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary" } ] }
Retrieve an instance network interface
This request retrieves a network interface for the calling instance.
GET /metadata/v1/instance/network_interfaces/{id}
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 between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/network_interfaces/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
Indicates whether source IP spoofing is allowed on this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and source IP spoofing is managed on the attached virtual network interface.
Example:
true
The date and time that the instance network interface was created.
If this instance has network attachments, this network interface was created as a read-only representation when its corresponding network attachment was created.
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The floating IPs associated with this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the floating IPs are associated with the attached virtual network interface.
The unique identifier for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the identifier is that of the corresponding network attachment.
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the name matches its corresponding network attachment.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-interface
The instance network interface port speed in Mbps.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the port speed is that of its corresponding network attachment.
Example:
1000
The primary IPv4 address.
If the address has not yet been selected, the value will be
0.0.0.0
.Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The resource type
Possible values: [
network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups targeting this instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the security groups are associated with the attached virtual network interface.
Possible values: number of items ≥ 1, contains only unique items
The status of the instance network interface.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the status is computed from them.
Possible values: [
available
,deleting
,failed
,pending
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
available
The associated subnet
Examples:{ "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" }
- subnet
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The instance network interface type.
If this instance has network attachments, this network interface is a read-only representation of its corresponding network attachment and its attached virtual network interface, and the type is that of its corresponding network attachment.
Possible values: [
primary
,secondary
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
primary
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
{ "allow_ip_spoofing": false, "created_at": "2024-10-15T03:24:32.993Z", "floating_ips": [ { "address": "203.0.113.1", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::floating-ip:r006-f45e0d90-12a8-4460-8210-290ff2ab75cd", "id": "r006-f45e0d90-12a8-4460-8210-290ff2ab75cd", "name": "my-floating-ip" } ], "id": "0717-d54eb633-98ea-459d-aa00-6a8e780175a7", "name": "my-instance-network-interface", "port_speed": 1000, "primary_ipv4_address": "10.0.1.5", "resource_type": "network_interface", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "status": "available", "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "type": "primary" }
List volume attachments
This request lists volume attachments for the calling instance.
GET /metadata/v1/instance/volume_attachments
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The volume attachments for the instance
Status Code
The volume attachments were retrieved successfully
An invalid authentication token was provided
The provided token is not authorized for this operation
{ "volume_attachments": [ { "bandwidth": 250, "created_at": "2024-10-24T16:32:05.000Z", "delete_volume_on_instance_delete": true, "device": { "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a-w8mw8" }, "id": "0717-fdb3642d-c849-4c29-97a9-03b868616f88", "name": "my-boot-volume-attachment", "status": "attached", "type": "boot", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-89b05e9a-e635-9464-9747-7ae3f9b03303", "id": "r006-89b05e9a-e635-9464-9747-7ae3f9b03303", "name": "my-boot-volume", "resource_type": "volume" } }, { "bandwidth": 250, "created_at": "2019-03-15T11:44:07.000Z", "delete_volume_on_instance_delete": false, "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-data-volume-attachment", "status": "attached", "type": "data", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } } ] }
Retrieve a volume attachment
This request retrieves a volume attachment for the calling instance.
GET /metadata/v1/instance/volume_attachments/{id}
Request
Path Parameters
The volume attachment identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/volume_attachments/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The maximum bandwidth (in megabits per second) for the volume when attached to this instance. This may be lower than the volume bandwidth depending on the configuration of the instance.
Example:
250
The date and time that the volume was attached
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
Indicates whether deleting the instance will also delete the attached volume
The unique identifier for this volume attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a
The name for this volume attachment. The name is unique across all volume attachments on the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume-attachment
The status of this volume attachment.
The enumerated values for this property may expand in the future.
Possible values: [
attached
,attaching
,deleting
,detaching
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The type of volume attachment.
The enumerated values for this property may expand in the future.
Possible values: [
boot
,data
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Information about how the volume is exposed to the instance operating system.
This property may be absent if the volume attachment's
status
is notattached
.Examples:{ "id": "0717-80b3e36e-41f4-40e9-bd56-beae81792a68-679qb" }
- device
A unique identifier for the device which is exposed to the instance operating system
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
The attached volume.
This property will be absent if the volume has not yet been provisioned.
Examples:{ "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" }
- volume
The CRN for this volume
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The unique identifier for this volume
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5
The name for this volume. The name is unique across all volumes in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-volume
The resource type
Possible values: [
volume
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
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
{ "bandwidth": 250, "created_at": "2019-03-15T11:44:07.000Z", "delete_volume_on_instance_delete": false, "id": "0717-82cbf856-9cbb-45fb-b62f-d7bcef32399a", "name": "my-data-volume-attachment", "status": "attached", "type": "data", "volume": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::volume:r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "id": "r006-1a6b7274-678d-4dfb-8981-c71dd9d4daa5", "name": "my-volume", "resource_type": "volume" } }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
A page of keys
Status Code
The keys were retrieved successfully
{ "keys": [ { "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "type": "rsa" }, { "created_at": "2024-10-01T21:46:21.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468", "fingerprint": "SHA256:XgUFJWiZbPehNHl706+mJbZdPDmSJh8G2ycvCYR2t5U", "id": "r006-a9f3ae27-4769-43e3-b5a3-a2856fbad468", "length": 2048, "name": "my-key-2", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6iw94c1htpVzC33sd874W6SeTZ9pGDZdY50vsnPUpYVfuU9WDscyy/NYVR74ZvSw1vN1QK57GEW46Uhh2JdvyQ1jiMPI6amu6bHiBqnWTo3HUFPBoxM9/3j0MhspjGyrO7JK3fOwyGrnquAqRq5BPibN8JLuZwCfVyucz98hEmnf9sEphJ5ab3ywVU3echaJZBEdUNEf2ZAHGGe5qnVW33y4PmRf5q90mPkJYwjTgTjZ3fPG2lV01S3eTbHV7zr1wxW4FSTFm7dVnfTURPzKc7mL4MS35s9gX73imvZL6O9ZH54IDoB8TBhx0U5657n6MoznFeXVcFSDLLpMXf7Gr", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "type": "rsa" } ] }
Request
Path Parameters
The key identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The date and time that the key was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The CRN for this key
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45
The fingerprint for this key. The value is returned base64-encoded and prefixed with the hash algorithm (always
SHA256
).Possible values: length ≥ 6, Value must match regular expression
^[ -~]*$
Example:
SHA256:yxavE4CIOL2NlsqcurRO3xGjkP6m/0mp8ugojH5yxlY
The unique identifier for this key
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-82679077-ac3b-4c10-be16-63e9c21f0f45
The length of this key (in bits)
Possible values: [
2048
,256
,4096
]The name for this key. The name must not be used by another key in the region. If unspecified, the name will be a hyphenated list of randomly-selected words.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$
Example:
my-key-1
The public SSH key, consisting of two space-separated fields: the algorithm name, and the base64-encoded key.
Possible values: length ≥ 4, Value must match regular expression
^[ -~]*$
Example:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En
The resource group for this key
Examples:{ "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }
- resource_group
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
The crypto-system for this key.
The enumerated values for this property may expand in the future.
Possible values: [
ed25519
,rsa
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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
{ "created_at": "2019-01-29T03:48:11.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::key:r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "fingerprint": "SHA256:RJ+YWs2kupwFGiJuLqY85twmcdLOUcjIc9cA6IR8n8E", "id": "r006-82679077-ac3b-4c10-be16-63e9c21f0f45", "length": 2048, "name": "my-key-1", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDDGe50Bxa5T5NDddrrtbx2Y4/VGbiCgXqnBsYToIUKoFSHTQl5IX3PasGnneKanhcLwWz5M5MoCRvhxTp66NKzIfAz7r+FX9rxgR+ZgcM253YAqOVeIpOU408simDZKriTlN8kYsXL7P34tsWuAJf4MgZtJAQxous/2byetpdCv8ddnT4X3ltOg9w+LqSCPYfNivqH00Eh7S1Ldz7I8aw5WOp5a+sQFP/RbwfpwHp+ny7DfeIOokcuI42tJkoBn7UsLTVpCSmXr2EDRlSWe/1M/iHNRBzaT3CK0+SwZWd2AEjePxSnWKNGIEUJDlUYp7hKhiQcgT5ZAnWU121oc5En", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "type": "rsa" }
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
A page of placement groups
Status Code
The placement groups were retrieved successfully
{ "placement_groups": [ { "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-placement-group", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" } ] }
Retrieve a placement group
This request retrieves a single placement group specified by identifier in the URL.
GET /metadata/v1/placement_groups/{id}
Request
Path Parameters
The placement group identifier
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
The date and time that the placement group was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The CRN for this placement group
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871
The unique identifier for this placement group
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-418fe842-a3e9-47b9-a938-1aa5bd632871
The lifecycle state of the placement group
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
stable
The name for this placement group. The name is unique across all placement groups in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-placement-group
The resource group for this placement group
Examples:{ "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }
- resource_group
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
The resource type
Possible values: [
placement_group
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The strategy for this placement group:
host_spread
: place on different compute hostspower_spread
: place on compute hosts that use different power sources
The enumerated values for this property may expand in the future.
Possible values: [
host_spread
,power_spread
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
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
{ "created_at": "2020-12-29T19:55:00.000Z", "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::placement-group:r006-418fe842-a3e9-47b9-a938-1aa5bd632871", "id": "r006-418fe842-a3e9-47b9-a938-1aa5bd632871", "lifecycle_state": "stable", "name": "my-placement-group", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "placement_group", "strategy": "host_spread" }
List virtual network interfaces
This request lists virtual network interfaces targeting the calling instance
GET /metadata/v1/virtual_network_interfaces
Request
Query Parameters
The API version, in format
YYYY-MM-DD
. For the API behavior documented here, specify any date between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
A page of virtual network interfaces
Status Code
The virtual network interfaces were retrieved successfully
{ "virtual_network_interfaces": [ { "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2024-10-15T03:24:32.993Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "enable_infrastructure_nat": false, "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "ips": [ { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6A", "name": "my-virtual-network-interface", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "protocol_state_filtering_mode": "auto", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "target": { "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-instance-network-attachment", "resource_type": "instance_network_attachment" }, "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "name": "us-south-1" } }, { "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2024-10-23T03:23:32.993Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-fa41aecb-4f21-423d-8082-630bfba1e1d9", "enable_infrastructure_nat": false, "id": "0717-fa41aecb-4f21-423d-8082-630bfba1e1d9", "ips": [ { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, { "address": "10.0.2.10", "id": "0717-948a1ea9-0ffe-4c9e-aa7b-be4dc2d3e749", "name": "my-reserved-ip-2", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6B", "name": "my-virtual-network-interface-2", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "protocol_state_filtering_mode": "auto", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-c0461da9-04be-4a26-ac87-94e06c19b840", "id": "0717-c0461da9-04be-4a26-ac87-94e06c19b840", "ipv4_cidr_block": "10.0.2.0/24", "name": "my-subnet-2", "resource_type": "subnet" }, "target": { "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-instance-network-attachment", "resource_type": "instance_network_attachment" }, "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "name": "us-south-1" } } ] }
Retrieve a virtual network interface
This request retrieves a virtual network interface targeting the calling instance.
GET /metadata/v1/virtual_network_interfaces/{id}
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 between2024-10-22
and2024-11-05
.Possible values: length = 10, Value must match regular expression
^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
Example:
2024-06-23
The API maturity. For the API behavior documented here, specify
beta
.Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/virtual_network_interfaces/$id?version=2024-11-05&maturity=beta" -H "Authorization: Bearer $instance_identity_token"
Response
Indicates whether source IP spoofing is allowed on this interface. If
false
, source IP spoofing is prevented on this interface. Iftrue
, source IP spoofing is allowed on this interface.Example:
true
Indicates whether this virtual network interface will be automatically deleted when
target
is deletedThe date and time that the virtual network interface was created
Possible values: 10 ≤ length ≤ 64, Value must match regular expression
^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$
The CRN for this virtual network interface
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
If
true
:- The VPC infrastructure performs any needed NAT operations.
floating_ips
must not have more than one floating IP.
If
false
:- Packets are passed unchanged to/from the virtual network interface, allowing the workload to perform any needed NAT operations.
allow_ip_spoofing
must befalse
.- Can only be attached to a
target
with aresource_type
ofbare_metal_server_network_attachment
.
Example:
true
The unique identifier for this virtual network interface
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-54eb57ee-86f2-4796-90bb-d7874e0831ef
The reserved IPs bound to this virtual network interface.
May be empty when
lifecycle_state
ispending
.Possible values: number of items ≥ 0
The lifecycle state of the virtual network interface
Possible values: [
deleting
,failed
,pending
,stable
,suspended
,updating
,waiting
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
stable
The name for this virtual network interface. The name is unique across all virtual network interfaces in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-virtual-network-interface
The reserved IP for this virtual network interface.
Examples:{ "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }
- primary_ip
The IP address.
If the address has not yet been selected, the value will be
0.0.0.0
.This property may expand to support IPv6 addresses in the future.
Possible values: 7 ≤ length ≤ 15, Value must match regular expression
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
Example:
192.168.3.4
The unique identifier for this reserved IP
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb
The name for this reserved IP. The name is unique across all reserved IPs in a subnet.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-reserved-ip
The resource type
Possible values: [
subnet_reserved_ip
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The protocol state filtering mode used for this virtual network interface. If
auto
, protocol state packet filtering is enabled or disabled based on the virtual network interface'starget
resource type:bare_metal_server_network_attachment
: disabledinstance_network_attachment
: enabledshare_mount_target
: enabled
Protocol state filtering monitors each network connection flowing over this virtual network interface, and drops any packets that are invalid based on the current connection state and protocol. See Protocol state filtering mode) for more information.
Possible values: [
auto
,disabled
,enabled
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
Example:
auto
The resource group for this virtual network interface
Examples:{ "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }
- resource_group
The unique identifier for this resource group
Possible values: length = 32, Value must match regular expression
^[0-9a-f]{32}$
Example:
fee82deba12e4c0fb69c3b09d1f12345
The name for this resource group
Possible values: 1 ≤ length ≤ 40, Value must match regular expression
^[a-zA-Z0-9-_ ]+$
Example:
my-resource-group
The resource type
Possible values: [
virtual_network_interface
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The security groups for this virtual network interface.
Possible values: number of items ≥ 1
The associated subnet
Examples:{ "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" }
- subnet
The CRN for this subnet
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The unique identifier for this subnet
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e
The name for this subnet. The name is unique across all subnets in the VPC.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-subnet
The resource type
Possible values: [
subnet
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The target of this virtual network interface.
- target
The unique identifier for this instance network attachment
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
0717-d54eb633-98ea-459d-aa00-6a8e780175a7
The name for this instance network attachment. The name is unique across all network attachments for the instance.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-instance-network-attachment
The resource type
Possible values: [
instance_network_attachment
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
The VPC this virtual network interface resides in.
Examples:{ "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" }
- vpc
The CRN for this VPC
Possible values: 9 ≤ length ≤ 512, Value must match regular expression
^crn:v[0-9]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]*:([a-z]\/[a-z0-9-]+)?:[a-z0-9-]*:[a-z0-9-]*:[a-zA-Z0-9-_\.\/]*$|^crn:\[\.\.\.\]$
Example:
crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The unique identifier for this VPC
Possible values: 1 ≤ length ≤ 64, Value must match regular expression
^[-0-9a-z_]+$
Example:
r006-4727d842-f94f-4a2d-824a-9bc9b02c523b
The name for this VPC. The name is unique across all VPCs in the region.
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
my-vpc
The resource type
Possible values: [
vpc
]Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-z][a-z0-9]*(_[a-z0-9]+)*$
If present, this property indicates the referenced resource has been deleted, and provides some supplementary information.
The zone this virtual network interface resides in.
Examples:{ "name": "us-south-1" }
- zone
The globally unique name for this zone
Possible values: 1 ≤ length ≤ 63, Value must match regular expression
^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$
Example:
us-south-1
The MAC address of the virtual network interface. May be absent if
lifecycle_state
ispending
.Possible values: length = 17, Value must match regular expression
^([0-9A-F]{2}:){5}[0-9A-F]{2}$
Example:
02:00:4D:45:45:4D
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
{ "allow_ip_spoofing": false, "auto_delete": true, "created_at": "2024-10-15T03:24:32.993Z", "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::virtual-network-interface:0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "enable_infrastructure_nat": false, "id": "0717-54eb57ee-86f2-4796-90bb-d7874e0831ef", "ips": [ { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" } ], "lifecycle_state": "stable", "mac_address": "02:00:04:00:C4:6A", "name": "my-virtual-network-interface", "primary_ip": { "address": "10.0.1.5", "id": "0717-6d353a0f-aeb1-4ae1-832e-1110d10981bb", "name": "my-reserved-ip", "resource_type": "subnet_reserved_ip" }, "protocol_state_filtering_mode": "auto", "resource_group": { "id": "fee82deba12e4c0fb69c3b09d1f12345", "name": "Default" }, "resource_type": "virtual_network_interface", "security_groups": [ { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::security-group:r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "id": "r006-be5df5ca-12a0-494b-907e-aa6ec2bfa271", "name": "my-security-group" } ], "subnet": { "crn": "crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::subnet:0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "id": "0717-7ec86020-1c6e-4889-b3f0-a15f2e50f87e", "name": "my-subnet", "resource_type": "subnet" }, "target": { "id": "35bd3f19-bdd4-434b-ad6a-5e9358d65e20", "name": "my-instance-network-attachment", "resource_type": "instance_network_attachment" }, "vpc": { "crn": "crn:v1:bluemix:public:is:us-south:a/aa2432b1fa4d4ace891e9b80fc104e34::vpc:r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "id": "r006-4727d842-f94f-4a2d-824a-9bc9b02c523b", "name": "my-vpc", "resource_type": "vpc" }, "zone": { "name": "us-south-1" } }