Skip to content

Update pod-id-assign-target-role.adoc #1059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: mainline
Choose a base branch
from
Open

Update pod-id-assign-target-role.adoc #1059

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 61 additions & 57 deletions latest/ug/manage-access/aws-access/pod-id-assign-target-role.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ include::../../attributes.txt[]
Learn how to configure account role access for Amazon EKS workloads using Pod Identity.
--

When running applications on Amazon Elastic Kubernetes Service (Amazon EKS), you might need to access {aws} resources that exist in the same or different {aws} accounts. This guide shows you how to set up access between these accounts using EKS Pod Identity, which enables your Kubernetes pods to access other {aws} resources.
When running applications on Amazon Elastic Kubernetes Service (Amazon EKS), you might need to access {aws} resources that exist in different {aws} accounts. This guide shows you how to set up cross account access using EKS Pod Identity, which enables your Kubernetes pods to access other {aws} resources using target roles.

== Prerequisites

Expand All @@ -20,11 +20,13 @@ Before you begin, ensure you have completed the following steps:

== How It Works

Pod Identity enables applications in your EKS cluster to access {aws} resources across accounts through a process called role chaining. When creating a Pod Identity association, you can provide two IAM roles—an link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] in the same account as your EKS cluster and a Target IAM Role from the account containing your {aws} resources (like S3 buckets or DynamoDB tables). The link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] must be in your EKS cluster's account due to https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_iam-passrole-service.html[IAM PassRole] requirements, while the Target IAM Role can be in any {aws} account. PassRole enables an {aws} entity to delegate role assumption to another service. EKS Pod Identity uses PassRole to connect a role to a Kubernetes service account, requiring both the role and the identity passing it to be in the same {aws} account as the EKS cluster. When your application pod needs to access {aws} resources, it requests credentials from Pod Identity. Pod Identity then automatically performs two role assumptions in sequence: first assuming the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"], then using those credentials to assume the Target IAM Role. This process provides your pod with temporary credentials that have the permissions defined in the target role, allowing secure access to resources in other {aws} accounts.
Pod Identity enables applications in your EKS cluster to access {aws} resources across accounts through a process called role chaining.

When creating a Pod Identity association, you can provide two IAM roles: an link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] in the same account as your EKS cluster and a Target IAM Role from the account containing your {aws} resources you wish to access, (like S3 buckets or RDS Databases). The link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] must be in your EKS cluster's account due to https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_iam-passrole-service.html[IAM PassRole] requirements, while the Target IAM Role can be in any {aws} account. PassRole enables an {aws} entity to delegate role assumption to another service. EKS Pod Identity uses PassRole to connect a role to a Kubernetes service account, requiring both the role and the identity passing it to be in the same {aws} account as the EKS cluster. When your application pod needs to access {aws} resources, it requests credentials from Pod Identity. Pod Identity then automatically performs two role assumptions in sequence: first assuming the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"], then using those credentials to assume the Target IAM Role. This process provides your pod with temporary credentials that have the permissions defined in the target role, allowing secure access to resources in other {aws} accounts.

== Caching considerations

Due to caching mechanisms, updates to an IAM role in an existing Pod Identity association may not take effect immediately in the pods running on your EKS cluster. The Pod Identity Agent caches IAM credentials based on the association's configuration at the time the credentials are fetched. If the association includes only an link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] ARN and no Target IAM Role, the cached credentials last for 6 hours. If the association includes both the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] ARN and a Target IAM Role, the cached credentials last for 59 minutes. Modifying an existing association, such as updating the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] ARN or adding a Target IAM Role, does not reset the existing cache. As a result, the agent will not recognize updates until the cached credentials refresh. To apply changes sooner, you can recreate the existing pods; otherwise, you will need to wait for the cache to expire.
Due to caching mechanisms, updates to an IAM role in an existing Pod Identity association may not take effect immediately in the pods running on your EKS cluster. The Pod Identity Agent caches IAM credentials based on the association's configuration at the time the credentials are fetched. If the association includes only an link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] and no Target IAM Role, the cached credentials last for 6 hours. If the association includes both the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] ARN and a Target IAM Role, the cached credentials last for 59 minutes. Modifying an existing association, such as updating the link:eks/latest/userguide/pod-id-role.html["EKS Pod Identity role",type="documentation"] ARN or adding a Target IAM Role, does not reset the existing cache. As a result, the agent will not recognize updates until the cached credentials refresh. To apply changes sooner, you can recreate the existing pods; otherwise, you will need to wait for the cache to expire.

== Step 1: Create and associate a Target IAM Role

Expand All @@ -45,30 +47,70 @@ In this step, you will establish a secure trust chain by creating and configurin
1. After creating the role, you'll be returned to the *Roles* list. Find and select the new role you created in the previous step (e.g., `MyCustomIAMTargetRole`).
2. Select the *Trust relationships* tab.
3. Click *Edit trust policy* on the right side.
4. In the policy editor, replace the default JSON with your trust policy. Replace the placeholder values for role name and `111122223333` in the IAM role ARN with the {aws} account ID hosting your EKS cluster. For example:
4. In the policy editor, replace the default JSON with your trust policy. Replace the placeholder values for role name and `111122223333` in the IAM role ARN with the {aws} account ID hosting your EKS cluster. You can also optionally use PrincipalTags in the role trust policy to authorize only specific service accounts from a given cluster and namespace to assume your target role . For example:

[source,json,subs="verbatim,attributes"]
----
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
},
"Action": "sts:AssumeRole"
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:root"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
],
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks-cluster-arn": "arn:aws:eks:us-east-1:111122223333:cluster/example-cluster",
"aws:PrincipalTag/kubernetes-namespace": "ExampleNameSpace",
"aws:PrincipalTag/kubernetes-service-account": "ExampleServiceAccountName"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
},
"Action": "sts:TagSession"
"ArnEquals": {
"aws:PrincipalARN": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
}
]
}
}
]
}
----
The above policy policy lets the role `eks-pod-identeity-primary-role` from AWS account 111122223333 with the relevant link:eks/latest/userguide/pod-id-abac.html["EKS Pod Identity Session Tags",type="documentation"] assume this role.

If you link:eks/latest/userguide/pod-id-abac.html#pod-id-abac-tags["Disabled Session Tags",type="documentation"] in your EKS Pod Identity, EKS Pod Identity also sets the `sts:ExternalId` with information about the cluster, namespace, and service account of a pod when assuming a target role.
[source,json,subs="verbatim,attributes"]
----
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "region/111122223333/cluster-name/namespace/service-account-name"
},
"ArnEquals": {
"aws:PrincipalARN": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
}
}
},
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:root"
},
"Action": "sts:TagSession"
}
]
}
----
The above policy helps ensure that only the expected cluster, namespace and service account can assume the target role.

=== Update the permission policy for EKS Pod Identity role

Expand Down Expand Up @@ -112,41 +154,3 @@ In this step, you will create an association between the Target IAM role and the
7. In the *Kubernetes namespace* field, enter the name of the namespace where you want to create the association (e.g., `my-app-namespace`). This defines where the service account resides.
8. In the *Kubernetes service account* field, enter the name of the service account (e.g., `my-service-account`) that will use the IAM credentials. This links the IAM role to the service account.
9. Choose *Create* to create the association.

== (Optional) Step 3: Add External Permissions to an IAM Target Role

At times, you might need to give a third party access to your {aws} resources (delegate access). For example, you decide to hire a third-party company called Example Corp to monitor your {aws} account and help optimize costs. In order to track your daily spending, Example Corp needs to access your {aws} resources. In this case, we recommend adding an `ExternalId` to the trust policy of your IAM Target Role to avoid possible https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html[Confused Deputy] issues.

=== Edit the trust policy

1. After creating the role, you'll be returned to the *Roles* list. Find and click the new role you created in the previous step (e.g., `MyCustomIAMTargetRole`).
2. Select the *Trust relationships* tab.
3. Click *Edit trust policy* on the right side.
4. In the policy editor, replace the default JSON with your trust policy. Replace the `ExternalId` placeholder value for `aws-region/other-account/cluster-name/namespace/service-account-name`, where "region" is the {aws} region of your cluster, "111122223333" is the other {aws} account ID, "cluster-name" is the EKS cluster name, "namespace" is the Kubernetes namespace, and "service-account-name" is the Kubernetes service account name. For example:

[source,json,subs="verbatim,attributes"]
----
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "region/111122223333/cluster-name/namespace/service-account-name"
}
},
{
"Effect": "Allow",
"Principal": {
"AWS": "{arn-aws}iam::111122223333:role/eks-pod-identity-primary-role"
},
"Action": "sts:TagSession"
}
]
}
----