Stay organized with collections
Save and categorize content based on your preferences.
This page explains what an AWS IAM instance profile is, why it's important in
the context of GKE on AWS, and how to update the instance profile.
What is an AWS IAM instance profile?
An instance profile is an AWS-specific concept. It consists of a set of
credentials that an Amazon EC2 instance uses to access various AWS resources.
More specifically, an instance profile is a kind of container for an IAM role
that can be attached to an EC2 instance. An instance profile confers permissions
to the EC2 instance, allowing the instance to interact with various AWS services
under the defined permissions. For more information, see
Using instance profiles.
How are instance profiles used in GKE on AWS?
Each control plane and each node pool within a GKE on AWS cluster
is associated with a unique AWS instance profile. Instance profiles in
GKE on AWS serve a dual purpose:
An instance profile grants GKE on AWS the permissions needed to manage
AWS resources. For example, they give the cluster autoscaler
the necessary permissions to scale the cluster by adding or removing EC2
instances based on workload demands.
An instance profile grants EC2 instances access to Google Cloud services.
For example the kubelet, running on an AWS machine, requires specific
permissions to supply image pull credentials to containerd. These
credentials are necessary for accessing and pulling images from Google's
private Artifact Registry or from Container Registry. In the context of
GKE on AWS, the EC2 instance profile associated with the cluster is
configured to impersonate Google's Machine Service Agents (such as the Node
Pool Machine Service Agent or the Control Plane Machine Service Agent). This
impersonation allows the cluster's EC2 instances to automatically
authenticate with Google's Artifact Registry or Container Registry.
Update instance profile
Updating the instance profile involves creating a new instance profile in AWS
with specific permissions, and then associating it with your
GKE on AWS cluster or node pool.
To correctly update the instance profile for your cluster or node pool, follow
these steps:
Create an IAM instance profile for your Amazon EC2 instances and add the
IAM role you need to the instance profile. For details, see
Using instance profiles.
Link the new instance profile to your GKE on AWS cluster or node
pool by running the following command in your Google Cloud CLI:
NEW_INSTANCE_PROFILE_NAME: the name of the new
AWS instance profile you created
These commands show only the relevant flags for updating the instance
profile, but you need to provide additional flags in order to run the
update command. For details, see
Update your AWS cluster parameters or
Update a node pool.
The incorrect update method
Understanding the wrong way to update an instance profile is important, because
it's an easy mistake to make that can cause cluster failures.
The wrong way to update an instance profile is to directly modify an existing
instance profile using the AWS Management Console or AWS CLI. Such changes can
disrupt GKE on AWS interaction with AWS resources. GKE on AWS
expects instance profiles to remain as they were when first linked to the
cluster or node pool. Altering them outside of GKE on AWS's management
tools can create a mismatch with the ID of the IAM role that's in the instance
profile. This mismatch can create a cluster failure.
The approach described in the preceding section ensures that updates are made
without disrupting GKE on AWS's integration with AWS.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Update AWS IAM instance profile\n\nThis page explains what an AWS IAM instance profile is, why it's important in\nthe context of GKE on AWS, and how to update the instance profile.\n\nWhat is an AWS IAM instance profile?\n------------------------------------\n\nAn instance profile is an AWS-specific concept. It consists of a set of\ncredentials that an Amazon EC2 instance uses to access various AWS resources.\nMore specifically, an instance profile is a kind of container for an IAM role\nthat can be attached to an EC2 instance. An instance profile confers permissions\nto the EC2 instance, allowing the instance to interact with various AWS services\nunder the defined permissions. For more information, see\n[Using instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html).\n\nHow are instance profiles used in GKE on AWS?\n---------------------------------------------\n\nEach control plane and each node pool within a GKE on AWS cluster\nis associated with a unique AWS instance profile. Instance profiles in\nGKE on AWS serve a dual purpose:\n\n1. An instance profile grants GKE on AWS the permissions needed to manage AWS resources. For example, they give the cluster autoscaler the necessary permissions to scale the cluster by adding or removing EC2 instances based on workload demands.\n2. An instance profile grants EC2 instances access to Google Cloud services. For example the `kubelet`, running on an AWS machine, requires specific permissions to supply image pull credentials to `containerd`. These credentials are necessary for accessing and pulling images from Google's private Artifact Registry or from Container Registry. In the context of GKE on AWS, the EC2 instance profile associated with the cluster is configured to impersonate Google's Machine Service Agents (such as the Node Pool Machine Service Agent or the Control Plane Machine Service Agent). This impersonation allows the cluster's EC2 instances to automatically authenticate with Google's Artifact Registry or Container Registry.\n\nUpdate instance profile\n-----------------------\n\nUpdating the instance profile involves creating a new instance profile in AWS\nwith specific permissions, and then associating it with your\nGKE on AWS cluster or node pool.\n\nTo correctly update the instance profile for your cluster or node pool, follow\nthese steps:\n\n1. Create an IAM instance profile for your Amazon EC2 instances and add the IAM role you need to the instance profile. For details, see [Using instance profiles](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-create-iam-instance-profile.html).\n2. Link the new instance profile to your GKE on AWS cluster or node\n pool by running the following command in your Google Cloud CLI:\n\n ### Link profile to cluster\n\n gcloud container aws clusters update \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e \\\n --update-instance-profile \\\n --instance-profile-name \u003cvar translate=\"no\"\u003eNEW_INSTANCE_PROFILE_NAME\u003c/var\u003e \\\n ...\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eCLUSTER_NAME\u003c/var\u003e: the name of your cluster\n - \u003cvar translate=\"no\"\u003eNEW_INSTANCE_PROFILE_NAME\u003c/var\u003e: the name of the new AWS instance profile you created\n\n ### Link profile to node pool\n\n gcloud container aws node-pools update \u003cvar translate=\"no\"\u003eNODE_POOL_NAME\u003c/var\u003e \\\n --update-instance-profile \\\n --instance-profile-name \u003cvar translate=\"no\"\u003eNEW_INSTANCE_PROFILE_NAME\u003c/var\u003e \\\n ...\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eNODE_POOL_NAME\u003c/var\u003e: the name of your node pool\n - \u003cvar translate=\"no\"\u003eNEW_INSTANCE_PROFILE_NAME\u003c/var\u003e: the name of the new AWS instance profile you created\n\n These commands show only the relevant flags for updating the instance\n profile, but you need to provide additional flags in order to run the\n `update` command. For details, see\n [Update your AWS cluster parameters](/kubernetes-engine/multi-cloud/docs/aws/how-to/update-cluster) or\n [Update a node pool](/kubernetes-engine/multi-cloud/docs/aws/how-to/update-node-pool).\n\n### The incorrect update method\n\nUnderstanding the wrong way to update an instance profile is important, because\nit's an easy mistake to make that can cause cluster failures.\n\nThe wrong way to update an instance profile is to directly modify an existing\ninstance profile using the AWS Management Console or AWS CLI. Such changes can\ndisrupt GKE on AWS interaction with AWS resources. GKE on AWS\nexpects instance profiles to remain as they were when first linked to the\ncluster or node pool. Altering them outside of GKE on AWS's management\ntools can create a mismatch with the ID of the IAM role that's in the instance\nprofile. This mismatch can create a cluster failure.\n\nThe approach described in the preceding section ensures that updates are made\nwithout disrupting GKE on AWS's integration with AWS."]]
