Configuring a Kubernetes service account to assume an IAM role
This topic covers how to configure a Kubernetes service account to assume an Amazon Identity and Access Management (IAM) role. Any Pods that are configured to use the service account can then access any Amazon Web 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 Getting 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 Creating an IAM OIDC provider for your cluster.
-
Version
2.12.3
or later or1.27.160
or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version withaws --version | cut -d / -f2 | cut -d ' ' -f1
. Package managers suchyum
,apt-get
, or Homebrew for macOS are often several versions behind the latest version of the Amazon CLI. To install the latest version, see Installing, updating, and uninstalling the Amazon CLI and Quick configuration withaws configure
in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may also be several versions behind the latest version. To update it, see Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide. -
The
kubectl
command line tool is installed on your device or Amazon 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.27
, you can usekubectl
version1.26
,1.27
, or1.28
with it. To install or upgradekubectl
, see Installing or updating kubectl. -
An existing
kubectl
config
file that contains your cluster configuration. To create akubectl
config
file, see Creating or updating a kubeconfig file for an Amazon EKS cluster.
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 Amazon 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 Amazon Web Services that you want your Pods to access. For a list of all actions for all Amazon Web 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 Amazon CLI. -
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-cn:iam::
111122223333
:oidc-provider/oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:default:my-service-account
", "oidc.eks.region-code
.amazonaws.com.cn/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-cn: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-cn: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-cn: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.cn/role-arn: arn:aws-cn:iam::111122223333
:role/my-role
Image pull secrets: <none> Mountable secrets:my-service-account
-token-qqjfl
Tokens:my-service-account
-token-qqjfl
[...]
-
-
(Optional) Configuring the Amazon Security Token Service endpoint for a service account. Amazon recommends using a regional Amazon STS endpoint instead of the global endpoint. This reduces latency, provides built-in redundancy, and increases session token validity.
Next step
Configuring Pods to use a Kubernetes service account