Help improve this page
Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.
Assign IAM roles to Kubernetes service accounts
This topic covers how to configure a Kubernetes service account to assume an AWS Identity and Access Management (IAM) role. Any Pods that are configured to use the service account can then access any AWS service that the role has permissions to access.
Prerequisites
-
An existing cluster. If you don't have one, you can create one by following one of the Get started with Amazon EKS guides.
-
An existing IAM OpenID Connect (OIDC) provider for your cluster. To learn if you already have one or how to create one, see Create an IAM OIDC provider for your cluster.
-
Version
2.12.3
or later or version1.27.160
or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use
. Package managers suchaws --version | cut -d / -f2 | cut -d ' ' -f1
yum
,apt-get
, or Homebrew for macOS are often several versions behind the latest version of the AWS CLI. To install the latest version, see Installing, updating, and uninstalling the AWS CLI and Quick configuration with aws configure in the AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see Installing AWS CLI to your home directory in the AWS CloudShell User Guide. -
The
kubectl
command line tool is installed on your device or AWS CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is1.29
, you can usekubectl
version1.28
,1.29
, or1.30
with it. To install or upgradekubectl
, see Set up kubectl and eksctl. -
An existing
kubectl
config
file that contains your cluster configuration. To create akubectl
config
file, see Connect kubectl to an EKS cluster by creating a kubeconfig file.
Assign IAM roles to Kubernetes service accounts
To associate an IAM role with a Kubernetes service account
-
If you want to associate an existing IAM policy to your IAM role, skip to the next step.
Create an IAM policy. You can create your own policy, or copy an AWS managed policy that already grants some of the permissions that you need and customize it to your specific requirements. For more information, see Creating IAM policies in the IAM User Guide.
-
Create a file that includes the permissions for the AWS services that you want your Pods to access. For a list of all actions for all AWS services, see the Service Authorization Reference.
You can run the following command to create an example policy file that allows read-only access to an Amazon S3 bucket. You can optionally store configuration information or a bootstrap script in this bucket, and the containers in your Pod can read the file from the bucket and load it into your application. If you want to create this example policy, copy the following contents to your device. Replace
my-pod-secrets-bucket
with your bucket name and run the command.cat >
my-policy.json
<<EOF { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-pod-secrets-bucket
" } ] } EOF -
Create the IAM policy.
aws iam create-policy --policy-name
my-policy
--policy-document file://my-policy.json
-
-
Create an IAM role and associate it with a Kubernetes service account. You can use either
eksctl
or the AWS CLI. -
(Optional) Configure the AWS Security Token Service endpoint for a service account. AWS recommends using a regional AWS STS endpoint instead of the global endpoint. This reduces latency, provides built-in redundancy, and increases session token validity.
Confirm configuration
Confirm that the role and service account are configured correctly.
-
Confirm that the IAM role's trust policy is configured correctly.
aws iam get-role --role-name
my-role
--query Role.AssumeRolePolicyDocumentAn example output is as follows.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::
111122223333
:oidc-provider/oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:default:my-service-account
", "oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:aud": "sts.amazonaws.com" } } } ] } -
Confirm that the policy that you attached to your role in a previous step is attached to the role.
aws iam list-attached-role-policies --role-name
my-role
--query AttachedPolicies[].PolicyArn --output textAn example output is as follows.
arn:aws:iam::
111122223333
:policy/my-policy
-
Set a variable to store the Amazon Resource Name (ARN) of the policy that you want to use. Replace
my-policy
with the name of the policy that you want to confirm permissions for.export policy_arn=arn:aws:iam::
111122223333
:policy/my-policy
-
View the default version of the policy.
aws iam get-policy --policy-arn $policy_arn
An example output is as follows.
{ "Policy": { "PolicyName": "
my-policy
", "PolicyId": "EXAMPLEBIOWGLDEXAMPLE
", "Arn": "arn:aws:iam::111122223333
:policy/my-policy
", "Path": "/", "DefaultVersionId": "v1
", [...] } } -
View the policy contents to make sure that the policy includes all the permissions that your Pod needs. If necessary, replace
1
in the following command with the version that's returned in the previous output.aws iam get-policy-version --policy-arn $policy_arn --version-id v
1
An example output is as follows.
{ "Version": "2012-10-17", "Statement": [
{ "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::my-pod-secrets-bucket" }
] }If you created the example policy in a previous step, then your output is the same. If you created a different policy, then the
example
content is different. -
Confirm that the Kubernetes service account is annotated with the role.
kubectl describe serviceaccount
my-service-account
-ndefault
An example output is as follows.
Name:
my-service-account
Namespace:default
Annotations: eks.amazonaws.com/role-arn: arn:aws:iam::111122223333
:role/my-role
Image pull secrets: <none> Mountable secrets:my-service-account
-token-qqjfl
Tokens:my-service-account
-token-qqjfl
[...]
Next step
Configure Pods to use a Kubernetes service account
Javascript is disabled or is unavailable in your browser.
To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.