AssumeRoleForPodIdentity
The Amazon EKS Auth API and the AssumeRoleForPodIdentity
action are only used
by the EKS Pod Identity Agent.
We recommend that applications use the AWS SDKs to connect to AWS services; if credentials from an EKS Pod Identity association are available in the pod, the latest versions of the SDKs use them automatically.
Request Syntax
POST /clusters/clusterName
/assume-role-for-pod-identity HTTP/1.1
Content-type: application/json
{
"token": "string
"
}
URI Request Parameters
The request uses the following URI parameters.
- clusterName
-
The name of the cluster for the request.
Length Constraints: Minimum length of 1. Maximum length of 100.
Pattern:
[0-9A-Za-z][A-Za-z0-9\-_]*
Required: Yes
Request Body
The request accepts the following data in JSON format.
- token
-
The token of the Kubernetes service account for the pod.
Type: String
Length Constraints: Minimum length of 1.
Pattern:
[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"assumedRoleUser": {
"arn": "string",
"assumeRoleId": "string"
},
"audience": "string",
"credentials": {
"accessKeyId": "string",
"expiration": number,
"secretAccessKey": "string",
"sessionToken": "string"
},
"podIdentityAssociation": {
"associationArn": "string",
"associationId": "string"
},
"subject": {
"namespace": "string",
"serviceAccount": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- assumedRoleUser
-
An object with the permanent IAM role identity and the temporary session name.
The ARN of the IAM role that the temporary credentials authenticate to.
The session name of the temporary session requested to AWS STS. The value is a unique identifier that contains the role ID, a colon (
:
), and the role session name of the role that is being assumed. The role ID is generated by IAM when the role is created. The role session name part of the value follows this format:eks-clustername-podname-random UUID
Type: AssumedRoleUser object
- audience
-
The identity that is allowed to use the credentials. This value is always
pods.eks.amazonaws.com
.Type: String
- credentials
-
The AWS Signature Version 4 type of temporary credentials.
Type: Credentials object
- podIdentityAssociation
-
The Amazon Resource Name (ARN) and ID of the EKS Pod Identity association.
Type: PodIdentityAssociation object
- subject
-
The name of the Kubernetes service account inside the cluster to associate the IAM credentials with.
Type: Subject object
Errors
For information about the errors that are common to all actions, see Common Errors.
- AccessDeniedException
-
You don't have permissions to perform the requested operation. The IAM principal making the request must have at least one IAM permissions policy attached that grants the required permissions. For more information, see Access management in the IAM User Guide.
HTTP Status Code: 400
- ExpiredTokenException
-
The specified Kubernetes service account token is expired.
HTTP Status Code: 400
- InternalServerException
-
These errors are usually caused by a server-side issue.
HTTP Status Code: 500
- InvalidParameterException
-
The specified parameter is invalid. Review the available parameters for the API request.
HTTP Status Code: 400
- InvalidRequestException
-
This exception is thrown if the request contains a semantic error. The precise meaning will depend on the API, and will be documented in the error message.
HTTP Status Code: 400
- InvalidTokenException
-
The specified Kubernetes service account token is invalid.
HTTP Status Code: 400
- ResourceNotFoundException
-
The specified resource could not be found.
HTTP Status Code: 404
- ServiceUnavailableException
-
The service is unavailable. Back off and retry the operation.
HTTP Status Code: 503
- ThrottlingException
-
The request was denied because your request rate is too high. Reduce the frequency of requests.
HTTP Status Code: 429
Examples
In the following example or examples, the Authorization header contents
(AUTHPARAMS
) must be replaced with an AWS Signature Version 4
signature. For more information about creating these signatures, see Signature
Version 4 Signing Process in the Amazon EKS General
Reference.
You need to learn how to sign HTTP requests only if you intend to manually
create them. When you use the AWS Command Line
Interface (AWS CLI)
Example
The following example assumes an IAM role with the EKS Pod Identity association called
my-association
in a cluster called
my-cluster
.
Sample Request
POST /clusters/my-cluster/assume-role-for-pod-identity HTTP/1.1
Host: eks-auth.us-west-2.api.aws
Accept-Encoding: identity
User-Agent: aws-cli/1.29.81 md/Botocore#1.31.81 ua/2.0 os/macos#22.6.0 md/arch#x86_64 lang/python#3.8.0 md/pyimpl#CPython cfg/retry-mode#legacy botocore/1.31.81
X-Amz-Date: 20231121T192727Z
Authorization: AUTHPARAMS
Content-length: 1043
{
"token": "eyJhbEXAMPLE"
}
Sample Response
HTTP/1.1 200 OK
Date: Fri, 22 Mar 2019 16:01:58 GMT
Content-Type: application/json
Content-Length: 682
x-amzn-RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
x-amz-apigw-id: W84GUEIbPHcFW2Q=
X-Amzn-Trace-Id: Root=1-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx
Connection: keep-alive
{
"assumedRoleUser": {
"arn": "arn:aws:sts::012345678910:assumed-role/my-role/eks-my-cluster-podname-randomUUID",
"assumeRoleId": "AROA123456789EXAMPLE:eks-my-cluster-podname-randomUUID"
},
"audience": "pods.eks.amazonaws.com",
"credentials": {
"accessKeyId": "ASIAIOSFODNN7EXAMPLE",
"expiration": 1.70061547E9,
"secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"sessionToken": "EXAMPLE"
},
"podIdentityAssociation": {
"associationArn": "arn:aws:eks:us-west-2:012345678910:podidentityassociation/my-association/a-abcdefghijklmnop1",
"associationId": "a-abcdefghijklmnop1"
},
"subject": {
"namespace": "my-namespace",
"serviceAccount": "my-serviceaccount"
}
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: