AWS Workload Identity
Overview
The AWS Workload Identity is a feature designed to enhance security and streamline access management for Control Plane managed Kubernetes clusters. This feature enables Pods running on Kubernetes clusters to assume an AWS IAM Role. By leveraging these IAM Roles, Pods can securely access AWS resources, adhering to the permissions defined in the corresponding IAM policies.
A key application of this feature is in scenarios where a Pod needs to interact with AWS services. For instance, a Pod requiring access to an S3 bucket can assume an IAM Role with the necessary permissions to perform actions on that bucket.
Enable AWS Workload Identity when secure access to AWS resources from Pods on the cluster is required.
Supported Providers
Prerequisites
- AWS Account
How to Enable
The AWS Workload Identity
add-on can be enabled for your Kubernetes cluster either during the cluster creation process or at any time thereafter. The following sections outline the methods for enabling the add-on:
At Cluster Creation
-
Through Cluster Manifest: Add the following snippet to your cluster manifest when creating the cluster:
YAMLspec: ... addOns: awsWorkloadIdentity: {} ...
-
Using the Console: If you’re creating the cluster through the console, navigate to
Add-ons
, find theAWS Workload Identity
add-on in the list of available add-ons, and toggle it on.
After Cluster Creation
If the AWS Workload Identity
add-on was not enabled during the cluster creation, you can still enable it using either of the following methods:
Using Manifest
Under spec.addOns
in the YAML manifest of the cluster, you can edit it either by navigating to the cluster in the Console and using the Edit & Apply
option for the cluster, or by applying the entire manifest using the cpln apply >_
option in the upper right corner or by using the cpln
CLI.
Add the following:
spec:
---
addOns:
awsWorkloadIdentity: {}
Using UI
- Navigate to Control Plane Console: Visit the Control Plane Console.
- Navigate to the Kubernetes cluster: In the Control Plane Console, navigate to
Kubernetes
in the left sidebar panel and click on the Kubernetes cluster for which you want to enable the dashboard. - Enable the Dashboard: Choose
Add-ons
and locate theAWS Workload Identity
add-on from the list of available add-ons, then toggle it on.
Usage Instructions
After enabling AWS Workload Identity, your Managed Kubernetes cluster becomes an identity provider for your Pods. Begin by creating an OIDC Identity Provider in your AWS account. Use the oidcProviderUrl
from your cluster, which is located in the status
section of the cluster. The method to access this URL is detailed below.
To grant a Pod access, ensure it uses a Kubernetes Service Account with the annotation: eks.amazonaws.com/role-arn: "arn:aws:iam::<ACCOUNT_ID>:role/IAM-ROLE-HERE"
. This setup is compatible with all Kubernetes Workloads, as they ultimately provision Pods.
Follow these steps below to configure.
Steps to configure access
-
Create OIDC Identity Provider in AWS
- Retrieve the cluster’s oidcProviderUrl:
cpln mk8s get -o json $cluster_name | jq -r '.status.oidcProviderUrl'
- Access the AWS console and navigate to IAM. In the left panel, under
Access management
, selectIdentity providers
and then clickAdd provider
. - Select
OpenID Connect
, paste theProvider URL
obtained in the previous step, and clickGet thumbprint
. - In the
Audience
field, entersts.amazonaws.com
.
- Retrieve the cluster’s oidcProviderUrl:
-
Retrieve and Save the Trust Policy JSON
- Obtain the trust policy template:
cpln mk8s get -o json $cluster_name | jq -r '.status.addOns.awsWorkloadIdentity.trustPolicy'
- Save the obtained policy to a file named
example-trust-policy.json
. Then, modify the trust policy by replacing<SERVICE_ACCOUNT>
and<NAMESPACE>
with the appropriate values:- For
<NAMESPACE>
, usedefault
. - For
<SERVICE_ACCOUNT>
, usemk8s-identity-example
.
- For
- Obtain the trust policy template:
-
Create an IAM Role
- You can create a new IAM Role using the AWS Console, or use an existing one. For creating a role via CLI, follow this example:
- Replace
<ACCOUNT_ID>
with your AWS Account ID. - Used the obtained trust policy from the previous step as
default-trust-policy.json
- Run the following command:
aws iam create-role --role-name "arn:aws:iam::<ACCOUNT_ID>:role/mk8s-identity-example" --assume-role-policy-document file://default-trust-policy.json
- Replace
- You can create a new IAM Role using the AWS Console, or use an existing one. For creating a role via CLI, follow this example:
-
Create Kubernetes Service Account and a Pod
Create the Kubernetes Service Account and a Pod in your Managed Kubernetes cluster. For guidance on accessing your cluster, refer to the documentation page of your Provider.-
Replace
<ACCOUNT_ID>
with your AWS Account ID in the following YAML configuration:YAMLapiVersion: v1 kind: ServiceAccount metadata: name: mk8s-identity-example namespace: default annotations: eks.amazonaws.com/role-arn: 'arn:aws:iam::<ACCOUNT_ID>:role/mk8s-identity-example' --- apiVersion: v1 kind: Pod metadata: name: identity-example namespace: default spec: terminationGracePeriodSeconds: 0 serviceAccountName: mk8s-identity-example containers: - command: - sleep - '99d' image: amazon/aws-cli:2.13.35 name: shell
-
The Pod
identity-example
can now access AWS resources using the IAM rolearn:aws:iam::<ACCOUNT_ID>:role/mk8s-identity-example
.
-