IBM Cloud Docs
Configure the metadata service

Configure the metadata service

Configure the metadata service by obtaining an instance identity access token from the metadata service. Optionally, generate an IAM access token from this token to access IAM-enabled services in the account.

Enabling or disabling the metadata service

The metadata service is disabled by default. To retrieve metadata from an instance, enable the service on new instances or existing instances by using the VPC UI, CLI, or API.

Enabling metadata service in the console

From the IBM Cloud® console, you can enable or disable the metadata service.

Enabling the metadata service for an existing instance in the console

Use the UI to enable the metadata service on an existing instance.

  1. Go to the list of instances. In the IBM Cloud console, click the Navigation Menu icon menu icon > Infrastructure VPC icon > Compute > Virtual server instances.

  2. Click the name of an instance to go to the details page.

  3. On the details page, scroll to Metadata.

  4. Click the toggle (appears green).

Enabling the metadata service when you create an instance in the console

The following procedure shows how to enable the metadata service when you create a virtual server instance.

  1. In the IBM Cloud console, click the Navigation Menu icon menu icon > Infrastructure VPC icon > Compute > Virtual server instances.

  2. Click Create.

  3. Provision the instance.

  4. Navigate to Advanced options and enable Metadata.

For more information about creating virtual server instances, see Creating virtual server instances in the console.

Disabling the metadata service in the console

This procedure shows how to disable the metadata service for an instance on which it is enabled. By default, the metadata service is disabled when you create a new instance.

  1. In the IBM Cloud console, click the Navigation Menu icon menu icon > Infrastructure VPC icon > Compute > Virtual server instances.

  2. Click an instance from the list to go to its details page.

  3. Under Metadata, the click the toggle button off (appears gray).

Enabling or disabling the metadata service on instance templates in the console

When you create an instance template, the enable metadata service toggle is disabled by default. Click the toggle to enable the service.

When you view the details of an existing instance template, the page indicates whether metadata was enabled or not for the template. You can't change the instance template metadata setting after you create the template.

Enabling or disabling metadata from the CLI

Use the CLI to enable the metadata service when you create a new instance or on an existing instance.

Before you begin:

  1. Before you can use the CLI, you must install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.

  2. Make sure that you created an IBM Cloud VPC.

Enabling or disabling the metadata service when you create an instance from the CLI

Run the ibmcloud is instance-create command and set the metadata-service property to true. The metadata service is disabled by default. In the response, you see Metadata service enabled set to true.

ibmcloud is instance-create test-instance-1 7002c1cd-9b0b-43ee-8112-5124dedbe84b us-south-1  bx2-2x8  0711-08206578-d749-49ea-86c9-1014622d1c6f --image-id 9f0050d0-636b-4fe6-82ea-931664fd9d91 --metadata-service true

Creating instance test under account VPC1 as user myuser@mycompany.com...

ID                         264060c2-e5e9-44d4-994f-eea4a6688172
Name                       test-instance-1
CRN                        crn:v1:public:is:us-south-1:a/a1234567::instance:264060c2-e5e9-44d4-994f-eea4a6688172
Status                     pending
Startable                  true
Profile                    bx2-2x8
Architecture               amd64
vCPUs                      2
Memory(GiB)                8
Bandwidth(Mbps)            4000
Metadata service enabled   true
Image                      ID                                          Name
                           9f0050d0-636b-4fe6-82ea-931664fd9d91        ibm-ubuntu-20-04-minimal-amd64-1

VPC                        ID                                          Name
                           7002c1cd-9b0b-43ee-8112-5124dedbe84b        test-vpc1

Zone                       us-south-1
Resource group             ID                                  Name
                           21cabbd983d9c4beb82690daab08717e8   Default

Created                    2022-08-08T22:12:11+05:30
Boot volume                ID   Name           Attachment ID                               Attachment name
                           -    PROVISIONING   954c1c47-906d-423f-a8c8-dd3adfafd278        my-vol-attachment1

Enabling or disabling the metadata service for an existing instance from the CLI

Run the ibmcloud is instance-update command and specify the instance ID. To enable the metadata service, set the metadata-service parameter to true; to disable, set it to false. An example command for enabling the service looks like this:

ibmcloud is instance-update e219a883-41f2-4680-810e-ee63ade35f98 --metadata-service true

Enabling or disabling the metadata service when you create new instance templates from the CLI

When you create an instance template from the CLI, you can indicate whether metadata is collected for instances created based on this template.

Use the ibmcloud is instance-create-from-template command and specify --metadata-service true option to enable or --metadata-service false option to disable. After you set the template value, you can't change it.

For example, to create an instance template with the metadata service enabled, run this command:

ibmcloud is instance-template-create my-template-name {template_id} us-south-1 mx2-2x16 {subnet_id} --image-id {image_id} --metadata-service true

When you create an instance from this template, specify the --metadata-service true option again to enable the service on the new instance:

ibmcloud is instance-create-from-template --template-id {template_id} --name my-instance --metadata-service true

If you override the instance template by running the ibmcloud is instance-template-create-override-source-template command, you can enable or disable the metadata service by specifying the --metadata-service option with true or false.

For more information about these commands, see the VPC CLI Reference. For more information about creating an instance template from the CLI, see Creating an instance template.

Enabling or disabling metadata with the API

Enabling or disabling the metadata service when you create a new instance with the API

The metadata service is disabled by default when you create an instance by making a POST /instances call.

You can enable the service by specifying the metadata_service parameter and setting enabled to true.

This example shows enabling the metadata service at instance creation:

curl -X POST "$vpc_api_endpoint/v1/instances?version=2024-11-12&generation=2"\
-H "Authorization: Bearer $iam_token"\
-d '{
      "image": {
         "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366"
      },
      "keys": [
         {
           "id": "363f6d70-0000-0001-0000-00000013b96c"
         }
      ],
      "name": "my-instance",
      "metadata_service": {
         "enabled": true
      },
      .
      .
      .
   }'

The response shows that the metadata parameter is set to true when you enable the service. You can also verify the metadata service setting by making a GET /instance/{id} call.

Enabling or disabling the metadata service for an existing instance with the API

To enable or disable the service from an existing instance, make a PATCH /instance/{instance_id} request and specify the metadata_service parameter. By default, the enabled property is set to false. To enable the service, set it to true.

This example call shows enabling the metadata service for an instance:

curl -X PATCH "$vpc_api_endpoint/v1/instances/$instance_id?version=2024-11-12&generation=2"\
    -H "Authorization: Bearer $iam_token"\
    -d '{
          "metadata_service": {
            "enabled": true
          }
      }'

The response shows that the metadata parameter is set to true when you enable the service. You can also verify the metadata service setting by making a GET /instance/{id} call.

Enabling or disabling the metadata service when you create new instance templates by using the API

When you create an instance template, you can set this value by making a POST /instance/templates request. By default, the enabled property is set to false. To enable it, set it to true.

For example,

curl -X POST "$vpc_api_endpoint/v1/instance/templates?version=2024-11-12&generation=2"\
    -H "Authorization: Bearer $iam_token"\
    -d '{
         "image": {
           "id": "3f9a2d96-830e-4100-9b4c-663225a3f872"
         },
         "keys": [
           {
             "id": "363f6d70-0000-0001-0000-00000013b96c"
           }
         ],
         "name": "my-instance-template",
         "metadata_service": {
             "enabled": true
         },
         "primary_network_interface": {
           "subnet": {
             "id": "0d933c75-492a-4756-9832-1200585dfa79"
           }
         },
         "profile": {
           "name": "bx2-2x8"
         },
         "vpc": {
           "id": "dc201ab2-8536-4904-86a8-084d84582133"
         },
         "zone": {
           "name": "us-south-1"
         }
       }'

You can't use the API to change the metadata-service setting after the instance template is created. If you disabled it for a template, create a new instance template with the metadata-service enabled set to true.

Configure metadata settings in the console

You can configure features of the metadata service in the console. When the metadata service is enabled, expand the metadata window to access the metadata service settings.

Select a trusted profile in the console

You can select an existing trusted profile for the metadata service.

Select a trusted profile when you provision an instance To select a trusted profile, navigate to the Default trusted profile option and select a trusted profile from a list of preexisting trusted profiles.

For more information, see Create a trusted profile for the instance.

Enable secure access in the console

You can enable secure access to the metadata service. When secure access is enabled, the metadata service is accessible only to the virtual server instance by encrypted HTTP secure protocol (HTTPS). When secure access is disabled, the metadata service is accessible only to the virtual server instance by unencrypted HTTP protocol. Secure access is disabled by default.

Additional properties might be required in the following scenarios:

Enable secure access when you provision an instance

To enable secure access when provisioning an instance, navigate to the Secure access setting in the Metadata window when you Create an instance from the Virtual server instances for VPC page. Toggle the secure access switch so that it displays Enabled.

Enable secure access on an existing instance

To enable secure access on an existing instance, navigate to the Secure access setting on the Instance details page of your instance.

Set the metadata hop limit in the console

You can set the hop limit for IP response packets from the metadata service. The hop limit can be any value from 1 (default) to 64. The metadata service must be enabled.

Set the metadata hop limit when you provision an instance

To set the hop limit when you provision an instance, go to the Hop limit setting in the Metadata window when you Create an instance from the Virtual server instances for VPC page. Specify a hop limit value between 1 and 64.

Set the metadata hop limit on an existing instance

To set the hop limit on an existing instance, go to the Hop limit setting on the Instance details page of your instance. Specify a hop limit value between 1 and 64.

Configure metadata settings by using the CLI

You can enable and disable features of the metadata service using the CLI.

The following example shows an instance with the metadata service enabled.

$ ibmcloud is instance instance-name -q

ID                                    0716_9cc6d74d-4b77-4cca-b1f4-31cc6edefe01
Name                                  instance-name
CRN                                   crn:v1:bluemix:public:is:us-south-1:a/a1234567::instance:0716_9cc6d74d-4b77-4cca-b1f4-31cc6edefe01
Status                                running
Availability policy on host failure   restart
Startable                             true
Profile                               bx2-2x8
Architecture                          amd64
vCPUs                                 2
Memory(GiB)                           8
Bandwidth(Mbps)                       4000
Volume bandwidth(Mbps)                1000
Network bandwidth(Mbps)               3000
Lifecycle Reasons                     Code   Message
                                      -      -

Lifecycle State                       stable
Metadata service                      Enabled   Protocol   Response hop limit
                                      false     http       1

Image                                 ID                                          Name
                                      r006-1025e040-7d6f-408c-b4db-6156dc986fc7   ibm-ubuntu-22-04-1-minimal-amd64-2

Numa Count                            1
VPC                                   ID                                          Name
                                      r006-ac1c1ae4-5573-42eb-9194-854c9a3d5555   fode

.
.
.

Enable secure access by using the CLI

You can enable secure access to the metadata service. When secure access is enabled, the metadata service is accessible only to the virtual server instance by encrypted HTTP Secure protocol (HTTPS). When secure access is disabled the metadata service is accessible only to the virtual server instance by unencrypted HTTP protocol. Secure access is disabled by default.

Certain properties might be required in the following scenarios:

Enable secure access when you provision an instance

To enable secure access when you provision an instance, specify a value for the --metadata-service-protocol option when you use the instance-create command. For secure access specify https. The default setting is unencrypted http.

ibmcloud is instance-create INSTANCE_NAME VPC ZONE_NAME PROFILE_NAME SUBNET ... [--metadata-service-protocol http | https] ...

--metadata-service-protocol value : The communication protocol to use for the metadata service
  endpoint. Applies only when the metadata service is enabled. One of: http, https. (default: "http")

To enable secure access on an existing instance, specify a value for the protocol sub-property of the metadata service when you use the instance-update command.

Set the metadata hop limit by using the CLI

You can set a hop limit for IP response packets from the metadata service by specifying a hop limit value between 1 (default) and 64 for the Response hop limit sub-property of the Metadata service property for your instance.

Set the metadata hop limit when you provision an instance

To set the metadata hop limit when you provision an instance, specify a hop limit value between 1 (default) and 64 for the --metadata-service-response-hop-limit option when you use the instance-create command.

ibmcloud is instance-create INSTANCE_NAME VPC ZONE_NAME PROFILE_NAME SUBNET ... [--metadata-service-response-hop-limit METADATA-SERVICE-RESPONSE-HOP-LIMIT] ...

--metadata-service-response-hop-limit value : The hop limit (IP time to live) for IP response packets
  from the metadata service. (default: 1)

Configure metadata settings by using the API

You can enable and disable features of the metadata service by using the API.

Enable secure access by using the API

You can enable secure access to the metadata service. When secure access is enabled, the metadata service is accessible only to the virtual server instance by encrypted HTTP Secure protocol (HTTPS). When secure access is disabled the metadata service is accessible only to the virtual server instance by unencrypted HTTP protocol. Secure access is disabled by default. Certain properties might be required in the following scenarios:

Enable secure access when you provision an instance

To enable secure access, when you provision an instance with the POST /instances method, specify a value for the metadata_service.protocol property for your instance. For secure access specify https. The default setting is unencrypted http.

Enable secure access on an existing instance

To enable secure access on an existing instance, use the PATCH /instances/{id} method to update the instance. Specify a value for the metadata_service.protocol property for your instance. For secure access specify https. The default setting is unencrypted http.

Set the metadata hop limit by using the API

You can set the hop limit for IP response packets from the metadata service using the metadata_service.response_hop_limit property

This property applies only when the metadata service is enabled by setting metadata_service.enabled to true. The default is false.

Set the metadata hop limit when you provision an instance

To set the response when you provision an instance, call the POST /instances method method, and specify the metadata_service.response_hop_limit property value between 1 (default) and 64.

This property applies only when the metadata service is enabled by setting metadata_service.enabled to true. The default is false.

Set the metadata hop limit on an existing instance

To set the response hop limit on an existing instance, call the PATCH /instances/{id} method, and specify the metadata_service.response_hop_limit property value between 1 (default) and 64.

Next steps

After you create an instance identity access token and enable the metadata service, you can retrieve metadata for the instance, SSH keys, and placement groups. For more information, see Use the metadata service.