Assume an IAM role to retrieve secrets with the ASCP
By default, the ASCP retrieves secrets with the Pod's IAM role, which the Pod gets through IAM Roles for Service Accounts (IRSA) or Amazon EKS Pod Identity.
If you set assumeRoleArn in the SecretProviderClass, the ASCP
uses the Pod's credentials to call AWS STS AssumeRole and retrieves the secrets as
the assumed role instead. If that role is in the account that owns the secrets, you don't need
a resource policy or cross-account sharing. The containers in the Pod aren't affected and keep
the Pod's own credentials.
Use assumeRoleArn in the following situations:
-
Your secrets are in a different account from the cluster, and you want to grant access with a role in that account instead of a resource policy on each secret and its AWS KMS key. For the resource policy approach, see Access AWS Secrets Manager secrets from a different account.
-
Your Pods need parameters from AWS Systems Manager Parameter Store in a different account.
-
SecretProviderClassresources that share a service account need different roles.
With Amazon EKS Pod Identity, you can instead assign a target IAM
role in the Pod Identity association. The Pod then receives the target role's
credentials, and you don't change the SecretProviderClass.
Required permissions
In this section, the target role is the role that the ASCP assumes, and the base role is the Pod's own role (the IRSA role or the Pod Identity role). They can be in the same account or in different accounts, and they need the following permissions:
-
The base role must have
sts:AssumeRolepermission on the target role ARN. It doesn't need Secrets Manager or Parameter Store permissions of its own.A Pod Identity base role must also have
sts:TagSessionpermission on the target role ARN, unless you disable session tags in the Pod Identity association. -
The target role must have
secretsmanager:GetSecretValueandsecretsmanager:DescribeSecretpermissions for the secrets to mount, andssm:GetParametersfor Parameter Store parameters. If a secret or parameter is encrypted with a customer managed key, it also needskms:Decrypton the key. For an example policy, see Example: Permission to read and describe individual secrets. -
The target role's trust policy must allow the base role to assume it. For an IRSA base role, allow
sts:AssumeRole.A Pod Identity base role carries session tags by default, and AWS STS passes them on to the
AssumeRolecall, so the trust policy must also allowsts:TagSession. If either the trust policy or the base role's permissions policy lacks it, the mount fails. Neither policy needssts:TagSessionif you disable session tags in the Pod Identity association. The following trust policy letsPodBaseRoleinAccount2assume the target role, and its condition keys limit that to one cluster, namespace, and service account. Replace the role name, account ID, and condition values with your own:{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::Account2:role/PodBaseRole" }, "Action": ["sts:AssumeRole", "sts:TagSession"], "Condition": { "StringEquals": { "aws:PrincipalTag/eks-cluster-arn": "arn:aws:eks:region:Account2:cluster/my-cluster", "aws:PrincipalTag/kubernetes-namespace": "my-namespace", "aws:PrincipalTag/kubernetes-service-account": "my-service-account" } } } ] }
Then set assumeRoleArn in the SecretProviderClass to the ARN of
the target role. You don't need to change anything else on the cluster. The ASCP retrieves
the objects as the target role, so a secret name without an ARN resolves in the target role's
account. For more information, see Example: Assume a role in another account.
How the ASCP assumes the role
The ASCP calls AssumeRole on every mount, including every rotation poll of
the Secrets Store CSI Driver, and the calls count against the AWS STS quota of the cluster's account.
Each session lasts 15 minutes and carries no external ID. The call goes to the AWS STS endpoint
in region, and to the one in failoverRegion if you set it. The role
session name is
,
cut at 64 characters, so CloudTrail events in the target role's account show which workload read the
secret.namespace@serviceAccountName
If AWS STS denies the call, the mount fails, and the Pod's FailedMount event
shows the AWS STS error with the Pod's role and the target role in it. To see the event, run
kubectl describe pod/.podId
With a Pod Identity base role, the error reads
not authorized to perform: sts:TagSession. AWS STS returns that same message when
the trust policy lacks sts:TagSession, when the base role's permissions policy
lacks it, and when the trust policy doesn't match the caller at all because of a wrong
principal or condition value. Check all three.