Create an IAM OIDC provider for your cluster
Your cluster has an OpenID Connect
-
An existing Amazon EKS cluster. To deploy one, see Get started with Amazon EKS.
-
Version
2.12.3
or later or version1.27.160
or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, useaws --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 AWS CLI. To install the latest version, see Installing and Quick configuration with aws configure in the AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see Installing AWS CLI to your home directory in the AWS CloudShell User Guide. -
The
kubectl
command line tool is installed on your device or AWS 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.29
, you can usekubectl
version1.28
,1.29
, or1.30
with it. To install or upgradekubectl
, see Set up kubectl and eksctl. -
An existing
kubectl
config
file that contains your cluster configuration. To create akubectl
config
file, see Connect kubectl to an EKS cluster by creating a kubeconfig file.
You can create an IAM OIDC provider for your cluster using eksctl
or the AWS Management Console.
Create OIDC provider (eksctl)
-
Version
0.197.0
or later of theeksctl
command line tool installed on your device or AWS CloudShell. To install or updateeksctl
, see Installationin the eksctl
documentation. -
Determine the OIDC issuer ID for your cluster.
Retrieve your cluster’s OIDC issuer ID and store it in a variable. Replace
my-cluster
with your own value.cluster_name=my-cluster
oidc_id=$(aws eks describe-cluster --name $cluster_name --query "cluster.identity.oidc.issuer" --output text | cut -d '/' -f 5)
echo $oidc_id
-
Determine whether an IAM OIDC provider with your cluster’s issuer ID is already in your account.
aws iam list-open-id-connect-providers | grep $oidc_id | cut -d "/" -f4
If output is returned, then you already have an IAM OIDC provider for your cluster and you can skip the next step. If no output is returned, then you must create an IAM OIDC provider for your cluster.
-
Create an IAM OIDC identity provider for your cluster with the following command.
eksctl utils associate-iam-oidc-provider --cluster $cluster_name --approve
Note
If you enabled the EKS VPC endpoint, the EKS OIDC service endpoint couldn’t be accessed from inside that VPC. Consequently, your operations such as creating an OIDC provider with
eksctl
in the VPC will not work and will result in a timeout when attempting to requesthttps://oidc.eks
. An example error message follows:. region
.amazonaws.com
** server cant find oidc.eks.region.amazonaws.com: NXDOMAIN
To complete this step, you can run the command outside the VPC, for example in AWS CloudShell or on a computer connected to the internet. Alternatively, you can create a split-horizon conditional resolver in the VPC, such as Route 53 Resolver to use a different resolver for the OIDC Issuer URL and not use the VPC DNS for it. For an example of conditional forwarding in CoreDNS, see the Amazon EKS feature request
Create OIDC provider (AWS Console)
-
Open the Amazon EKS console
. -
In the left pane, select Clusters, and then select the name of your cluster on the Clusters page.
-
In the Details section on the Overview tab, note the value of the OpenID Connect provider URL.
-
Open the IAM console at https://console.aws.amazon.com/iam/
. -
In the left navigation pane, choose Identity Providers under Access management. If a Provider is listed that matches the URL for your cluster, then you already have a provider for your cluster. If a provider isn’t listed that matches the URL for your cluster, then you must create one.
-
To create a provider, choose Add provider.
-
For Provider type, select OpenID Connect .
-
For Provider URL, enter the OIDC provider URL for your cluster.
-
For Audience, enter
sts.amazonaws.com
. -
(Optional) Add any tags, for example a tag to identify which cluster is for this provider.
-
Choose Add provider.
Next step: Assign IAM roles to Kubernetes service accounts