Configuration requirements by operating system

The metadata service uses an internal network configured with the link-local IP address 169.254.169.253 to provide secure, instance-level authentication. Configuration requirements and procedures vary by operating system (OS). The following table provides the configuration requirements for each supported OS.

Power Virtual Server uses the cloud-init package to configure connectivity from a VSI to the metadata service. The cloud-init package is required on each supported operating system to access the Power Virtual Server metadata service. Ensure that any custom image that you create includes the cloud-init package.

Enabling access to the metadata service for a new VSI by using the user interface

You can enable access to the metadata service when you create a VSI by using the Power Virtual Server user interface.

To enable access to the metadata service when you create a VSI, complete the following steps:

1. Log in to the IBM Cloud catalog with your credentials.

2. In the search box, type Power Virtual Server and click the Power Virtual Server tile.

3. Click Workspaces in the navigation panel. The Workspaces page with a list of existing workspaces is displayed.

4. From the Workspaces page, select a workspace in which you want to create a VSI. The "Virtual server instances" page is displayed.

5. Click Create instance. The "Create virtual server instance" page is displayed.

6. In the General section, expand Advanced configurations and set Metadata service to on. The Default trusted profile (optional) field and the Auto link toggle are displayed.

   You can optionally configure the following settings:

   • Default trusted profile: To grant the VSI access to IAM-enabled services through a trusted profile, click Select trusted profile. The "Select default Trusted Profile" dialog is displayed. Select a trusted profile from the list and click Select Trusted Profile.

   • Auto link: Set the Auto link toggle:

     • Enabled Default. The VSI cloud resource name (CRN) is automatically added to the selected trusted profile and the profile is available to the VSI when the VSI starts.

     • Disabled: If the selected trusted profile is not configured with rule-based filters, you must manually link the trusted profile to the VSI by using the IAM Trusted Profile UI, CLI, or API before the VSI can use the trusted profile.

If the selected trusted profile is created from an enterprise account template, by default the child account cannot edit the trusted profile. This causes the Auto link operation to fail. To avoid this error, disable Auto link and either create the trust relationship directly in IAM, or add a rule to the trusted profile template that grants access to VSIs from the child account. For more information, see Creating trusted profile templates.

7. Click Continue and complete the remaining steps to create the VSI. For more information about creating a VSI, see Creating a Power Virtual Server instance.

Enabling access to the metadata service for an existing VSI by using the user interface

When you enable access to the metadata service API endpoint for an existing VSI, the VSI must be in the Shutoff state.

To enable access to the metadata service for an existing VSI, complete the following steps:

1. Log in to the IBM Cloud catalog with your credentials.

2. In the search box, type Power Virtual Server and click the Power Virtual Server tile.

3. Click Workspaces in the navigation panel. The Workspaces page with a list of existing workspaces is displayed.

4. Select the workspace that contains the VSI for which you want to enable the metadata service. The "Virtual server instances" page with a list of existing VSIs is displayed.

5. Select the VSI for which you want to enable the metadata service. The "Virtual server instance details" page for the selected VSI is displayed.

   If you enable access to the metadata service for a VSI that is in the Active state, you might need to complete additional steps to configure the network. For more information about configuration steps, see Configuration requirements by operating system.

6. On the Overview tab, go to the Metadata service section, and click the Edit icon. The "Edit Metadata service details" panel is displayed.

7. Set Metadata service to Access enabled. The Default trusted profile (optional) field and the Auto link toggle are displayed.

   You can optionally configure the following settings:

   • Default trusted profile: To grant the VSI access to IAM-enabled services through a trusted profile, click Select trusted profile. The "Select default Trusted Profile" dialog is displayed. Select a trusted profile from the list and click Select Trusted Profile.

   • Auto link: Set the Auto link toggle:

     • Enabled (default): The VSI CRN is automatically added to the selected trusted profile and the profile is available to the VSI when the VSI starts.

     • Disabled: If the selected trusted profile is not configured with rule-based filters, you must manually link the trusted profile to the VSI by using the IAM Trusted Profile UI, CLI, or API before the VSI can use the trusted profile.

If the selected trusted profile is created from an enterprise account template, by default the child account cannot edit the trusted profile. This causes the Auto link operation to fail. To avoid this error, disable Auto link and either create the trust relationship directly in IAM, or add a rule to the trusted profile template that grants access to VSIs from the child account. For more information, see Creating trusted profile templates.

8. Click Save.

Disabling access to the metadata service by using the user interface

You can disable access to the metadata service for a VSI on which the service is currently enabled. By default, access to the metadata service is disabled when you create a VSI.

AIX VSIs must be in the Shutoff state before you can disable access to the metadata service.

To disable access to the metadata service for a VSI, complete the following steps:

1. Log in to the IBM Cloud catalog with your credentials.

2. In the search box, type Power Virtual Server and click the Power Virtual Server tile.

3. Click Workspaces in the navigation panel. The Workspaces page with a list of existing workspaces is displayed.

4. Select the workspace that contains the VSI for which you want to disable the metadata service. The "Virtual server instances" page with a list of existing VSIs is displayed.

5. Select the VSI for which you want to disable the metadata service. The "Virtual server instance details" page for the selected VSI is displayed.

6. On the Overview tab, go to the Metadata service section and click the Edit icon. The "Edit Metadata service details" panel is displayed.

7. Set Metadata service to Access disabled.

   If you disable access to the metadata service for a VSI that is in the Active state, you might need to configure the network interface. For more information about configuration steps, see Configuring and troubleshooting metadata service connectivity.

8. Click Save.

Enabling or disabling access to the metadata service by using the CLI

You can use the Power Virtual Server CLI to enable or disable access to the metadata service when you create a VSI or update an existing VSI.

Before you begin, install the IBM Cloud CLI and the Power Virtual Server CLI plug-in. For more information, see Installing the IBM Power Virtual Server CLI plug-in.

ibmcloud pi instance create test-instance-1 --image IMAGE_ID --subnets SUBNET_ID --processors 0.5 --processor-type shared --memory 4 --metadata-service true

ibmcloud pi instance create test-instance-2 --default-trusted-profile "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5" --default-trusted-profile-autolink false

ibmcloud pi instance update INSTANCE_ID --metadata-service true

Enabling or disabling access to the metadata service by using the API

You can use the Power Virtual Server API to enable or disable access to the metadata service when you create a VSI or update an existing VSI.

curl -X POST "$power_api_endpoint/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances" \
-H "Authorization: Bearer $iam_token" \
-d '{
      "imageID": "7200-05-09",
      "keyPairName": "test1",
      "memory": 2,
      "networks": [
        {
          "networkID": "public-192_168_194_2-6-VLAN_2044"
        }
      ],
      "pinPolicy": "",
      "placementGroup": "",
      "procType": "shared",
      "processors": 0.25,
      "serverName": "vsnTest2",
      "storageType": "tier3",
      "sysType": "s922",
      "volumeIDs": [],
      "metadataService": {
         "enabled": true
      }
   }'

curl -X PUT "$power_api_endpoint/pcloud/v1/cloud-instances/{cloud_instance_id}/pvm-instances/{pvm_instance_id}"\
    -H "Authorization: Bearer $iam_token"\
    -d '{
          "metadataService": {
            "enabled": true
          }
      }'

"defaultTrustedProfile": {
      "autolink": false,
   "target": {
       "id": "Profile-9fd84246-7df4-4667-94e4-8ecde51d5ac5"
   }
  },

Identity access token

An identity access token is a security credential that you use to access the Power Virtual Server metadata and identity services. An identity access token is a signed token that contains claims based on information about the VSI.

Communication between the VSI and the metadata service remains within the Power Virtual Server environment. You can access the APIs only from a Power Virtual Server VSIs. You cannot access the metadata and Identity APIs by using the Power Virtual Server user interface or CLI.

To obtain the identity access token, send a PUT https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/token request to the Power Virtual Server Identity API.

curl -X PUT "https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/token" \
-H "Metadata-Flavor: ibm" \
-d '{}'

In the request, you can specify an expiration time for the token. The default expiration value is 5 minutes, but you can specify any value between 5 seconds and 1 hour. The following example shows how to specify an expiration time:

curl -X PUT "https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/token" \
-H "Metadata-Flavor: ibm" \
-d '{"expires_in": 360}'

The API response contains the identity access token. Use this token to access the metadata service.

The following JSON response shows an identity access token, the time when the token was created, the time when it expires, and the expiration time that you set. The identity access token in this example expires in 5 minutes.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5...",
  "created_at": "2025-06-10T11:08:39.363Z",
  "expires_at": "2025-06-10T11:13:39.363Z",
  "expires_in": 300
}

You can then use the identity access token to authenticate with the metadata service and call the metadata-instance API. For more information, see Retrieving metadata from a virtual server instance.

You can also generate an IAM token from the identity access token to call IAM-enabled services. For more information, see Generating an IAM token from an identity access token.

Generating an IAM token from an identity access token

You can use an identity access token to generate an IAM token from a VSI that has an associated trusted profile. You can then use the generated IAM token to access IAM-enabled services, such as IBM Cloud Object Storage and Cloud Database Service. The generated IAM token has a short lifetime and can be used like an API key.

Send a POST https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/iam_tokens request and optionally specify the trusted profile ID that is associated with the VSI. If you configured a default trusted profile for the VSI, you can omit the trusted profile parameter, and the request uses the default trusted profile ID.

The following example shows a request to generate an IAM token:

iam_token=`curl -X POST "https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/iam_tokens" \
-H "Authorization: Bearer $identity_token" \
-H "Metadata-Flavor: ibm" \
-d '{
      "trusted_profile": {
        "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
      }
    }'| jq -r '(.access_token)'`

The JSON response shows the IAM token.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6I8...",
  "created_at": "2025-06-10T14:10:15Z",
  "expires_at": "2025-06-10T15:10:15Z",
  "expires_in": 3600
}

For more information about how to use a trusted profile to call IAM-enabled services, see Using a trusted profile to call IAM-enabled services.

Using the identity access token to generate an IAM token

The following example shows how to use the identity access token to generate an IAM token:

curl -X POST "https://api.metadata.power-iaas.cloud.ibm.com/identity/v1/iam_tokens" \
-H "Authorization: Bearer $identity_token" \
-H "Metadata-Flavor: ibm" \
-d '{"trusted_profile": {"id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"}}'

When you exchange the identity access token, you must specify which trusted profile to use for the IAM token request. If you do not specify a trusted profile, the API uses the default trusted profile that was linked when the VSI was provisioned. If multiple trusted profiles are linked to a VSI, you can use a different trusted profile by specifying its ID or CRN.

Use the IAM token to call IAM-enabled services.

Use iptables firewall to limit access on Linux

Use the iptables firewall utility on Linux to restrict access between the metadata service link-local address (trusted network) and the other network interfaces on your VSI. Define iptables rules on the VSI to control which traffic is allowed and which is blocked.

The following example uses Linux iptables and its owner module to prevent the Apache Web server from accessing the metadata link-local address (169.254.169.253) based on the default Apache user ID. The example uses a deny rule to reject all metadata requests from any process that runs as the Apache user.

sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.253 --match owner --uid-owner apache --jump REJECT

The metadata service endpoint (169.254.169.253) is accessible to all commands, processes, and software applications that are run within a VSI. The API endpoint is not accessible outside the VSI. This configuration adds an additional layer of security to the metadata service.

You can also use allow rules to define access for specific users or groups. Allow rules require you to decide which software needs access to the VSI metadata. These rules can prevent software from accidentally accessing the metadata service if you later change the software or configuration on the VSI.

You can also use allow rules to manage group access by adding or removing users from a permitted group without changing the firewall rule.

The following example prevents all processes from accessing the metadata service, except processes that run under the trustworthy-user account:

sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.253 --match owner ! --uid-owner trustworthy-user --jump REJECT

Limit trusted profiles for compute resource identities

Limit the trusted profiles that you create for compute resource identities in IAM. If a VSI does not need a compute resource identity, do not assign a compute resource identity.

You can also update existing trusted profiles by redefining the trust relationship, assigning access policies, and updating session limits. For more information, see Updating trusted profiles.