This documentation is for the most recent version of Anthos clusters on AWS, released on November 3rd. See the Release notes for more information. For documentation on the previous generation of Anthos clusters on AWS, see Previous generation.

Enable the IMDS emulator

Stay organized with collections Save and categorize content based on your preferences.

This page explains how you can enable the IMDS emulator, which emulates the AWS instance metadata service (IMDS). You can run the emulator as a sidecar to enable legacy workloads to run in Anthos clusters on AWS node pools. If you have legacy workloads that don't support Workload Identity directly, use this emulator to access IMDS data.

Limitations

  • Your cluster must use a Kubernetes version of 1.24 or later.
  • The emulator is not supported in the previous generation of Anthos clusters on AWS.
  • The IMDS emulator server only serves credential requests (API_VERSION/meta-data/iam/security-credentials/). All other metadata requests return a 404 error.
  • A sidecar deployment requires the init container to have the NET_ADMIN and NET_RAW security context capacities. If you're not sure if the container has these contexts, consult your security team.
  • The AWS STS token can last for one hour. The role token from EC2 metadata can last for 24 hours. This shouldn't affect your usage of the emulator, but you might need to know this information during a security audit.
  • The IMDS emulator only emulates IMDSv1 responses. IMDSv2 is not supported.

Enable the emulator

To enable the IMDS emulator, add a label and an annotation to metadata for a Pod. You can also enable the emulator using a Deployment, DaemonSet, or any other resource that creates Pods:

  1. Add the following label and value to your Pod:

    gkemulticloud.googleapis.com/aws-imds-emulator-enabled: "True"
    

    The only acceptable value for this label is True. All other values (including true with a lowercase t) disable the emulator.

  2. Add the following annotation to your Pod:

    gkemulticloud.googleapis.com/aws-imds-emulator-role-arn: ARN_ROLE
    

    Replace ARN_ROLE with an Amazon Resource Name (ARN) that specifies the role that you want the resource to have.

Example

The following example is a Pod with the IMDS emulator enabled:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  labels:
    gkemulticloud.googleapis.com/aws-imds-emulator-enabled: "True"
  annotations:
    gkemulticloud.googleapis.com/aws-imds-emulator-role-arn: "arn:aws:iam::123456789012:role/my-example-role"
spec:
 serviceAccountName: my-sa
 containers:
 - name: nginx
   image: nginx