Accessing metadata from an instance

Most often, you want to access metadata from a running instance and use it to bootstrap an instance. This topic describes the general procedure for enabling the metadata service, creating an instance identity access token, and accessing the metadata.

Before you begin

Install the IBM Cloud CLI and the VPC CLI plug-in. For more information, see the CLI prerequisites.
After the installation of the VPC CLI plug-in, set the target to generation 2 by running the ibmcloud is target --gen 2 command.
Make sure that you created an IBM Cloud VPC.
Configure a floating IP so that you can SSH into the virtual servers over the floating IP address.

General procedure to access instance metadata

Table 1 describes the steps that are involved in accessing instance metadata. The information provides the context for each step and links to specific information for completing the step. In an actual environment, steps 3 - 5 would more likely be started by your instance's initialization software at startup or by using cloud-init.

Table 1. General procedure for accessing instance metadata
Step	Context	Service Called	User Action
1	IBM Cloud	VPC UI, CLI, API	Create a virtual server instance and enable the metadata service on it. (The service is disabled by default.) You can also enable the service on an existing instance, in the UI or with the API. With the API, make a call to create a virtual server instance that is configured with the metadata service enabled. Customer user data is specified on instance creation.
2	IBM Cloud		Sign on to the instance by using the normal startup operations.
3	VPC instance	Metadata service	Provide a `curl` command to call the metadata token service to acquire an instance identity access token.
4	VPC instance	Metadata service	Provide a `curl` command to call the metadata service. The token from the previous step is passed and the metadata is returned.
5	VPC instance		Parse the JSON returned in the previous step to acquire the user data.

End-to-end procedure for accessing metadata from an instance

Log in to IBM Cloud CLI.
Go to an existing instance. Use the following command to locate a running instance in which to enable the metadata service. The instance must have a VPC that is associated with it.
```
ibmcloud is instance {instance_id}
```
List security group rules so you can SSH into the virtual servers over the floating IP address:
```
ibmcloud is security-group-rules {security_group_id}
```
SSH to get a connection into the virtual server to issue the APIs for the metadata service.
Log in to the virtual server. You can be running a stock image or custom image. The metadata service is supported on all stock and custom images, and CPU profiles. Now, the floating IP is assigned. The security groups are in place, and you're now working within the virtual server.
Make an API call to the metadata token service to retrieve an instance identity access token. Specify how long the token is valid, for example 3600 seconds (1 hour). In this example, the command is run through the jq parser to format the JSON response. You can choose the parser that you prefer.
```
export instance_identity_token=`curl -X PUT "http://169.254.169.254/instance_identity/v1/token?version=2022-03-01"\
  -H "Metadata-Flavor: ibm"\
  -H "Accept: application/json"\
  -d '{
        "expires_in": 3600
      }' | jq -r '(.access_token)'`
```
The response is the instance identity access token payload.
You can now make an API call to the metadata service. The first call is for the initialization information:
```
curl -X GET "http://169.254.169.254/metadata/v1/instance/initialization?version=2022-03-01"\
   -H "Accept: application/json"\
   -H "Authorization: Bearer $instance_identity_token"\
   | jq -r
```
Information in the response shows the SSH key and user data that was specified when the virtual server was provisioned. If you configured passwords, that information is also returned.

Access metadata about the instance, such as volume attachments, dedicated hosts, memory, vCPUs, and so on.

curl -X GET "http://169.254.169.254/metadata/v1/instance?version=2022-03-01"\
   -H "Accept: application/json"\
   -H "Authorization: Bearer $instance_identity_token"\
   | jq -r

Continue by making calls for other metadata for the instance, SSH keys, and placement groups by issuing REST API calls within the instance. For more information, see Use the instance metadata service.

Next steps

Use the trusted profile for the instance and generate an IAM token from the instance identity access token to other IAM-enabled services. See Using a trusted profile to call IAM-enabled services.