Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors Examples See Also

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) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. When you use these tools, you don't need to learn how to sign requests yourself.

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"
    }
}