> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Workload Identity

> Allow pods on Managed Kubernetes clusters to securely assume AWS IAM Roles for accessing AWS resources like S3, DynamoDB, and other services.

## 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

* [AWS](../aws)
* [Hetzner](../hetzner)
* [Generic](../generic)

## 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:

  ```yaml YAML theme={null}
  spec:
    ...
    addOns:
      awsWorkloadIdentity: {}
  ...
  ```

* **Using the Console**: If you're creating the cluster through the console, navigate to `Add-ons`, find the `AWS 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](/cli-reference/overview).

Add the following:

```yaml YAML theme={null}
spec:
---
addOns:
  awsWorkloadIdentity: {}
```

#### Using UI

1. **Navigate to Control Plane Console**: Visit the [Control Plane Console](https://console.cpln.io/console/).
2. **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.
3. **Enable the AWS Workload Identity add-on**: Choose `Add-ons` and locate the `AWS Workload Identity` add-on from the list of available add-ons, then toggle it on.

## Setup

If the role provided to Control Plane includes the ability to create the OIDC Identity Provider, then it will be created for you automatically.
If the role provided to Control Plane does not include access to create OIDC Identity Providers, then the following manual steps must be completed before AWS Workload Identity or any other dependent add-ons will function.

After enabling AWS Workload Identity, an [OIDC Identity Provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) for each cluster must be created in your AWS account before it can be used.
The `oidcProviderUrl` for the OIDC Identity Provider is in the status of the cluster.

1. **Create OIDC Identity Provider in AWS**

   1. Retrieve the cluster's **oidcProviderUrl**:

      CLI

      ```
      cpln mk8s get -o json $cluster_name | jq -r '.status.oidcProviderUrl'
      ```

      UI

      1. From the Managed Kubernetes cluster in the UI, select `View` from the `Actions` drop down in the upper right corner.

         A new window will open showing the content of the Managed Kubernetes object in the Control Plane API.

      2. Toggle the `Slim` button so it is turned off.

      3. The `providerUrl` is shown in the object at `.status.addOns.awsWorkloadIdentity.oidcProviderConfig`

   2. Access the AWS console and navigate to **IAM**. In the left panel, under `Access management`, select `Identity providers` and then click `Add provider`.

   3. Select `OpenID Connect`, paste the `Provider URL` obtained in the previous step, and click `Get thumbprint`.

   4. In the `Audience` field, enter `sts.amazonaws.com`.

## Usage Instructions

After enabling AWS Workload Identity, your Managed Kubernetes cluster becomes an identity provider for your Pods.

To grant a Pod access, ensure it uses a [Kubernetes Service Account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-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](https://kubernetes.io/docs/concepts/workloads/), as they ultimately provision Pods.

Follow these steps below to configure.

### Steps to configure access

1. **Retrieve and Save the Trust Policy JSON**

   1. Obtain the trust policy template:
      ```
      cpln mk8s get -o json $cluster_name | jq -r '.status.addOns.awsWorkloadIdentity.trustPolicy'
      ```
   2. 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>`, use `default`.
      * For `<SERVICE_ACCOUNT>`, use `mk8s-identity-example`.

2. **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:
     * Use the obtained trust policy from the previous step as `default-trust-policy.json`
     * Run the following command:
       ```
       aws iam create-role --role-name "mk8s-identity-example" --assume-role-policy-document file://default-trust-policy.json
       ```

3. **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:

     ```yaml YAML theme={null}
     apiVersion: 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 role `arn:aws:iam::<ACCOUNT_ID>:role/mk8s-identity-example`.