Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).

# Deploying to Amazon EKS with a workflow
<a name="deploy-action-eks"></a>

**Tip**  
For a tutorial that shows you how to use the **Deploy to Kubernetes cluster ** action, see [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).

This section describes how to deploy a containerized application into a Kubernetes cluster using a CodeCatalyst workflow. To accomplish this, you must add the **Deploy to Kubernetes cluster** action to your workflow. This action deploys your application to a Kubernetes cluster that you have set up in Amazon Elastic Kubernetes Service (EKS) using one or more Kubernetes manifest files. For a sample manifest, see [deployment.yaml](deploy-tut-eks.md#deploy-tut-eks-source-files-deployment-yml) in [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).

For more information about Kubernetes, see the [Kubernetes Documentation](https://kubernetes.io/docs/home/).

For more information about Amazon EKS, see [What is Amazon EKS?](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) in the *Amazon EKS User Guide*.

**Topics**
+ [

## How the 'Deploy to Kubernetes cluster' action works
](#deploy-action-eks-howitworks)
+ [

## Runtime image used by the 'Deploy to Amazon EKS' action
](#deploy-action-eks-runtime)
+ [

# Tutorial: Deploy an application to Amazon EKS
](deploy-tut-eks.md)
+ [

# Adding the 'Deploy to Kubernetes cluster' action
](deploy-action-eks-adding.md)
+ [

# 'Deploy to Kubernetes cluster' variables
](deploy-action-eks-variables.md)
+ [

# 'Deploy to Kubernetes cluster' action YAML
](deploy-action-ref-eks.md)

## How the 'Deploy to Kubernetes cluster' action works
<a name="deploy-action-eks-howitworks"></a>

The **Deploy to Kubernetes cluster** works as follows:

1. At runtime, the action installs the Kubernetes `kubectl` utility to the CodeCatalyst compute machine where the action is running. The action configures `kubectl` to point to the Amazon EKS cluster you provided when you configured the action. The `kubectl` utility is necessary to run the `kubectl apply` command, next.

1. The action runs the `kubectl apply -f my-manifest.yaml` command, which carries out the instructions in *my-manifest.yaml* to deploy your application as a set of containers and pods into the configured cluster. For more information on this command, see the [kubectl apply](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply) topic in the *Kubernetes Reference Documentation*.

## Runtime image used by the 'Deploy to Amazon EKS' action
<a name="deploy-action-eks-runtime"></a>

The **Deploy to Amazon EKS** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).

# Tutorial: Deploy an application to Amazon EKS
<a name="deploy-tut-eks"></a>

In this tutorial, you learn how to deploy a containerized application into Amazon Elastic Kubernetes Service using an Amazon CodeCatalyst workflow, Amazon EKS, and a few other AWS services. The deployed application is a simple 'Hello, World\$1' website built on an Apache web server Docker image. The tutorial walks you through the required preparation work such as setting up a development machine and an Amazon EKS cluster, and then describes how to create a workflow to build the application and deploy it into the cluster.

After the initial deployment is complete, the tutorial instructs you to make a change to your application source. This change causes a new Docker image to be built and pushed to your Docker image repository with new revision information. The new revision of the Docker image is then deployed into Amazon EKS.

**Tip**  
Instead of working your way through this tutorial, you can use a blueprint that does a complete Amazon EKS setup for you. You'll need to use the **EKS App Deployment** blueprint. For more information, see [Creating a project with a blueprint](projects-create.md#projects-create-console-template).

**Topics**
+ [

## Prerequisites
](#deploy-tut-eks-prereqs)
+ [

## Step 1: Set up your development machine
](#deploy-tut-eks-dev-env-create)
+ [

## Step 2: Create an Amazon EKS cluster
](#deploy-tut-eks-cluster)
+ [

## Step 3: Create an Amazon ECR image repository
](#deploy-tut-eks-ecr)
+ [

## Step 4: Add source files
](#deploy-tut-eks-source-files)
+ [

## Step 5: Create AWS roles
](#deploy-tut-eks-roles)
+ [

## Step 6: Add AWS roles to CodeCatalyst
](#deploy-tut-eks-import-roles)
+ [

## Step 7: Update the ConfigMap
](#deploy-tut-eks-configmap)
+ [

## Step 8: Create and run a workflow
](#deploy-tut-eks-workflow)
+ [

## Step 9: Make a change to your source files
](#deploy-tut-eks-change)
+ [

## Clean up
](#deploy-tut-eks-cleanup)

## Prerequisites
<a name="deploy-tut-eks-prereqs"></a>

Before you begin this tutorial:
+ You need an Amazon CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ In your space, you need an empty project called:

  ```
  codecatalyst-eks-project
  ```

  Use the **Start from scratch** option to create this project.

  For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty).
+ In your project, you need an empty CodeCatalyst **source repository** called:

  ```
  codecatalyst-eks-source-repository
  ```

  For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).
+ In your project, you need a CodeCatalyst CI/CD **environment** (not a Dev Environment) called:

  ```
  codecatalyst-eks-environment
  ```

  Configure this environment as follows:
  + Choose any type, such as **Non-production**.
  + Connect your AWS account to it. 
  + For the **Default IAM role**, choose any role. You'll specify a different role later.

  For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md).

## Step 1: Set up your development machine
<a name="deploy-tut-eks-dev-env-create"></a>

The first step in this tutorial is to configure a development machine with a few tools that you'll use throughout this tutorial. These tools are:
+ the `eksctl` utility – for cluster creation
+ the `kubectl` utility – a prerequisite for `eksctl`
+ the AWS CLI – also a prerequisite for `eksctl`

You can install these tools on your existing development machine if you have one, or you can use a CodeCatalyst Dev Environment, which is Cloud-based. The benefit of a CodeCatalyst Dev Environment is that it's easy to spin up and take down, and is integrated with other CodeCatalyst services, allowing you to work through this tutorial in fewer steps.

This tutorial assumes you'll be using a CodeCatalyst Dev Environment.

The following instructions describe a quick way to launch a CodeCatalyst Dev Environment and configure it with the required tools, but if you want detailed instructions, see:
+ [Creating a Dev Environment](devenvironment-create.md) in this guide.
+ [Installing kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) in the **Amazon EKS User Guide**.
+ [Installing or upgrading eksctl](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) in the **Amazon EKS User Guide**.
+ [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) in the *AWS Command Line Interface User Guide*.

**To launch a Dev Environment**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to your project, `codecatalyst-eks-project`.

1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 

1. Choose the name of your source repository, `codecatalyst-eks-source-repository`.

1. Near the top choose **Create Dev Environment**, and then choose **AWS Cloud9 (in browser)**.

1. Make sure that **Work in existing branch** and **main** are selected, and then choose **Create**.

   Your Dev Environment launches in a new browser tab, and your repository (`codecatalyst-eks-source-repository`) is cloned into it.

**To install and configure kubectl**

1. In the Dev Environment terminal, enter:

   ```
   curl -o kubectl https://amazon-eks.s3.us-west-2.amazonaws.com/1.18.9/2020-11-02/bin/linux/amd64/kubectl
   ```

1. Enter:

   ```
   chmod +x ./kubectl
   ```

1. Enter:

   ```
   mkdir -p $HOME/bin && cp ./kubectl $HOME/bin/kubectl && export PATH=$PATH:$HOME/bin
   ```

1. Enter:

   ```
   echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
   ```

1. Enter:

   ```
   kubectl version --short --client
   ```

1. Check that a version appears.

   You have now installed `kubectl`.

**To install and configure eksctl**
**Note**  
`eksctl` is not strictly required because you can use `kubectl` instead. However, `eksctl` has the benefit of automating much of the cluster configuration, and is therefore the tool recommended for this tutorial.

1. In the Dev Environment terminal, enter:

   ```
   curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
   ```

1. Enter:

   ```
   sudo cp /tmp/eksctl /usr/bin
   ```

1. Enter:

   ```
   eksctl version
   ```

1. Check that a version appears.

   You have now installed `eksctl`.

**To verify that the AWS CLI is installed**

1. In the Dev Environment terminal, enter:

   ```
   aws --version
   ```

1. Check that a version appears to verify that the AWS CLI is installed.

   Complete the remaining procedures to configure the AWS CLI with the necessary permissions to access AWS.

**To configure the AWS CLI**

You must configure the AWS CLI with access keys and a session token to give it access to AWS services. The following instructions provide a quick way to configure the keys and token, but if you want detailed instructions, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.

1. Create an IAM Identity Center user, as follows:

   1. Sign in to the AWS Management Console and open the AWS IAM Identity Center console at [https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/).

      (You might need to choose **Enable** if you've never signed in to IAM Identity Center before.)
**Note**  
Make sure you sign in using the AWS account that is connected to your CodeCatalyst space. You can verify which account is connected by navigating to your space and choosing the **AWS accounts** tab. For more information, see [Creating a space](spaces-create.md).

   1. In the navigation pane, choose **Users**, and then choose **Add user**.

   1. In **Username**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. Under **Password**, choose **Generate a one-time password that you can share with this user**.

   1. In **Email address** and **Confirm email address**, enter an email address that doesn't already exist in IAM Identity Center.

   1. In **First name**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. In **Last name**, enter:

      ```
      codecatalyst-eks-user
      ```

   1. In **Display name**, keep:

      ```
      codecatalyst-eks-user codecatalyst-eks-user
      ```

   1. Choose **Next**.

   1. On the **Add user to groups** page, choose **Next**.

   1. On the **Review and add user** page, review the information and choose **Add user**.

      A **One-time password** dialog box appears.

   1. Choose **Copy** and then paste the sign-in information to a text file. The sign-in information consists of the AWS access portal URL, a user name, and a one-time password.

   1. Choose **Close**.

1. Create a permission set, as follows:

   1. In the navigation pane, choose **Permission sets**, and then choose **Create permission set**.

   1. Choose **Predefined permission set** and then select **AdministratorAccess**. This policy provides full permissions to all AWS services. 

   1. Choose **Next**.

   1. In **Permission set name**, remove `AdministratorAccess` and enter:

      ```
      codecatalyst-eks-permission-set
      ```

   1. Choose **Next**.

   1. On the **Review and create** page, review the information and choose **Create**.

1. Assign the permission set to `codecatalyst-eks-user`, as follows:

   1. In the navigation pane, choose **AWS accounts**, and then select the check box next to the AWS account that you're currently signed in to.

   1. Choose **Assign users or groups**.

   1. Choose the **Users** tab.

   1. Select the check box next to `codecatalyst-eks-user`.

   1. Choose **Next**.

   1. Select the check box next to `codecatalyst-eks-permission-set`.

   1. Choose **Next**.

   1. Review the information and choose **Submit**.

      You have now assigned `codecatalyst-eks-user` and `codecatalyst-eks-permission-set` to your AWS account, binding them together.

1. Obtain `codecatalyst-eks-user`'s access keys and session token, as follows:

   1. Make sure you have the AWS access portal URL and the username and one-time password for `codecatalyst-eks-user`. You should have copied this information to a text editor earlier.
**Note**  
If you do not have this information, go to the `codecatalyst-eks-user` details page in IAM Identity Center, choose **Reset password**, **Generate a one-time password [...]**, and **Reset password** again to display the information on the screen.

   1. Sign out of AWS.

   1. Paste the AWS access portal URL into your browser's address bar.

   1. Sign in with:
      + **Username**:

        ```
        codecatalyst-eks-user
        ```
      + **Password**:

        *one-time-password*

   1. In **Set new password**, enter a new password and choose **Set new password**.

      An **AWS account** box appears on the screen.

   1. Choose **AWS account**, and then choose the name of the AWS account to which you assigned the `codecatalyst-eks-user` user and permission set.

   1. Next to `codecatalyst-eks-permission-set`, choose **Command line or programmatic access**.

   1. Copy the commands in the middle of the page. They look similar to the following:

      ```
      export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE" 
      export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" 
      export AWS_SESSION_TOKEN="session-token"
      ```

      ...where *session-token* is a long random string.

1. Add the access keys and session token to the AWS CLI, as follows:

   1. Return to your CodeCatalyst Dev Environment.

   1. At the terminal prompt, paste the commands you copied. Press Enter.

      You have now configured the AWS CLI with access keys and a session token. You can now use AWS CLI to complete the tasks required by this tutorial.
**Important**  
If at any time during this tutorial you see messages similar to:  
`Unable to locate credentials. You can configure credentials by running "aws configure".`  
Or:  
`ExpiredToken: The security token included in the request is expired`  
...it's because your AWS CLI session has expired. In this case, do *not* run the `aws configure` command. Instead, use the instructions in step 4 of this procedure that starts with `Obtain codecatalyst-eks-user's access key and session token` to refresh your session.

## Step 2: Create an Amazon EKS cluster
<a name="deploy-tut-eks-cluster"></a>

In this section, you create a cluster in Amazon EKS. The instructions below describe a quick way to create the cluster using `eksctl`, but if you want detailed instructions, see:
+ [Getting started with eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) in the **Amazon EKS User Guide**

  or
+ [Getting started with the console and AWS CLI](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html) in the **Amazon EKS User Guide** (this topic provides `kubectl` instructions for creating the cluster) 

**Note**  
[Private clusters](https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html) are not supported by the CodeCatalyst integration with Amazon EKS.

**Before you begin**

Make sure you have completed the following tasks on your development machine:
+ Installed the `eksctl` utility.
+ Installed the `kubectl` utility.
+ Installed the AWS CLI and configured it with access keys and a session token.

For information on how to complete these tasks, see [Step 1: Set up your development machine](#deploy-tut-eks-dev-env-create).

**To create a cluster**
**Important**  
Do not use the Amazon EKS service's user interface to create the cluster because the cluster won't be configured correctly. Use the `eksctl` utility, as described in the following steps.

1. Go to your Dev Environment.

1. Create a cluster and nodes:

   ```
   eksctl create cluster --name codecatalyst-eks-cluster --region us-west-2
   ```

   Where:
   + *codecatalyst-eks-cluster* is replaced with the name you want to give your cluster.
   + *us-west-2* is replaced with your Region.

   After 10-20 minutes, a message similar to the following appears: 

   `EKS cluster "codecatalyst-eks-cluster" in "us-west-2" region is ready`
**Note**  
You will see multiple `waiting for CloudFormation stack` messages while AWS creates your cluster. This is expected.

1. Verify that your cluster was created successfully:

   ```
   kubectl cluster-info
   ```

   You will see a message similar to the following, indicating a sucessful cluster creation:

   ```
   Kubernetes master is running at https://long-string.gr7.us-west-2.eks.amazonaws.com
   CoreDNS is running at https://long-string.gr7.us-west-2.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
   ```

## Step 3: Create an Amazon ECR image repository
<a name="deploy-tut-eks-ecr"></a>

In this section, you create a private image repository in Amazon Elastic Container Registry (Amazon ECR). This repository stores the Docker image for the tutorial.

For more information about Amazon ECR, see the *Amazon Elastic Container Registry User Guide*.

**To create an image repository in Amazon ECR**

1. Go to your Dev Environment.

1. Create an empty repository in Amazon ECR:

   ```
   aws ecr create-repository --repository-name codecatalyst-eks-image-repo
   ```

   Replace *codecatalyst-eks-image-repo* with the name you want to give the Amazon ECR repository.

   This tutorial assumes you named your repository `codecatalyst-eks-image-repo`.

1. Display the Amazon ECR repository’s details:

   ```
   aws ecr describe-repositories \
         --repository-names codecatalyst-eks-image-repo
   ```

1. Note the `“repositoryUri”:` value, for example, `111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo`.

   You need it later when adding the repository to your workflow. 

## Step 4: Add source files
<a name="deploy-tut-eks-source-files"></a>

In this section, you add application source files to your source repository (`codecatalyst-eks-source-repository`). They consist of:
+ An `index.html` file – Displays a 'Hello, World\$1' message in the browser.
+ A Dockerfile – Describes the base image to use for your Docker image and the Docker commands to apply to it.
+ A `deployment.yaml` file – The Kubernetes manifest that defines the Kubernetes service and deployment. 

The folder structure is as follows:

```
|— codecatalyst-eks-source-repository
   |— Kubernetes
      |— deployment.yaml
   |— public-html
   |  |— index.html
   |— Dockerfile
```

**Topics**
+ [

### index.html
](#deploy-tut-eks-source-files-index)
+ [

### Dockerfile
](#deploy-tut-eks-source-files-dockerfile)
+ [

### deployment.yaml
](#deploy-tut-eks-source-files-deployment-yml)

### index.html
<a name="deploy-tut-eks-source-files-index"></a>

The `index.html` file displays a 'Hello, World\$1' message in the browser. 

**To add the index.html file**

1. Go to your Dev Environment.

1. In `codecatalyst-eks-source-repository`, create a folder called `public-html`.

1. In `/public-html`, create a file called `index.html` with the following contents:

   ```
   <html>
     <head>
       <title>Hello World</title>
       <style>
         body {
         background-color: black;
         text-align: center;
         color: white;
         font-family: Arial, Helvetica, sans-serif;
         }  
       </style>
     </head>
     <body>
       <h1>Hello, World!</h1>
     </body>
   </html>
   ```

1. At the terminal prompt, enter:

   ```
   cd /projects/codecatalyst-eks-source-repository
   ```

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add public-html/index.html"
   git push
   ```

   The `index.html` is added to your repository in a `public-html` folder. 

### Dockerfile
<a name="deploy-tut-eks-source-files-dockerfile"></a>

The Dockerfile describes the base Docker image to use and the Docker commands to apply to it. For more information about the Dockerfile, see the [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/).

The Dockerfile specified here indicates to use the Apache 2.4 base image (`httpd`). It also includes instructions for copying a source file called `index.html` to a folder on the Apache server that serves webpages. The `EXPOSE` instruction in the Dockerfile tells Docker that the container is listening on port 80.

**To add the Dockerfile**

1. In `codecatalyst-eks-source-repository`, create a file called `Dockerfile` with the following contents:

   ```
   FROM httpd:2.4
   COPY ./public-html/index.html /usr/local/apache2/htdocs/index.html
   EXPOSE 80
   ```

   Do not include a file extension.
**Important**  
The Dockerfile must reside in your repository’s root folder. The workflow’s `Docker build` command expects it to be there.

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add Dockerfile"
   git push
   ```

   The Dockerfile is added to your repository.

### deployment.yaml
<a name="deploy-tut-eks-source-files-deployment-yml"></a>

In this section, you add a `deployment.yaml` file to your repository. The `deployment.yaml` file is a Kubernetes manifest that defines two Kubernetes resources types or *kinds* to run: a 'service' and a 'deployment'.
+ The 'service' deploys a load balancer into Amazon EC2. The load balancer provides you with an Internet-facing public URL and standard port (port 80) that you can use to browse to the 'Hello, World\$1' application. 
+ The 'deployment' deploys three pods, and each pod will contain a Docker container with the 'Hello, World\$1' application. The three pods are deployed onto the nodes that were created when you created the cluster.

The manifest in this tutorial is short; however, a manifest can include any number of Kubernetes resource types, such as pods, jobs, ingresses, and network policies. Further, you can use multiple manifest files if your deployment is complex.

**To add a deployment.yaml file**

1. In `codecatalyst-eks-source-repository`, create a folder called `Kubernetes`.

1. In `/Kubernetes`, create a file called `deployment.yaml` with the following contents:

   ```
   apiVersion: v1
   kind: Service
   metadata:
     name: my-service
     labels:
       app: my-app
   spec:
     type: LoadBalancer
     selector:
       app: my-app
     ports:
       - protocol: TCP
         port: 80
         targetPort: 80
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-deployment
     labels:
       app: my-app
   spec:
     replicas: 3
     selector:
       matchLabels:
         app: my-app
     template:
       metadata:
         labels:
           app: my-app
       spec:
         containers:
         - name: codecatalyst-eks-container
           # The $REPOSITORY_URI and $IMAGE_TAG placeholders will be replaced by actual values supplied by the build action in your workflow
           image: $REPOSITORY_URI:$IMAGE_TAG
           ports:
           - containerPort: 80
   ```

1. Add, commit, and push:

   ```
   git add .
   git commit -m "add Kubernetes/deployment.yaml"
   git push
   ```

   The `deployment.yaml` file is added to your repository in a folder called `Kubernetes`. 

You have now added all your source files.

Take a moment to double-check your work and make sure you placed all the files in the correct folders. The folder structure is as follows:

```
|— codecatalyst-eks-source-repository
   |— Kubernetes
      |— deployment.yaml
   |— public-html
   |  |— index.html
   |— Dockerfile
```

## Step 5: Create AWS roles
<a name="deploy-tut-eks-roles"></a>

In this section, you create AWS IAM roles that your CodeCatalyst workflow will need in order to function. These roles are:
+ **Build role** – Grants the CodeCatalyst build action (in the workflow) permission to access your AWS account and write to Amazon ECR and Amazon EC2.
+ **Deploy role** – Grants the CodeCatalyst **Deploy to Kubernetes cluster** action (in the workflow) permission to access your AWS account and Amazon EKS.

For more information about IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS Identity and Access Management User Guide*.

**Note**  
To save time, you can create a single role, called the `CodeCatalystWorkflowDevelopmentRole-spaceName` role, instead of the two roles listed previously. For more information, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has very broad permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. This tutorial assumes you are creating the two roles listed previously.

To create the build and deploy roles, complete the following series of procedures.

**1. To create a trust policy for both roles**

1. Go to your Dev Environment.

1. In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-trust-policy.json` with the following contents:

**2. To create the build policy for the build role**
+ In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-build-policy.json` with the following contents:

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "ecr:*",
                  "ec2:*"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```

**3. To create the deploy policy for the deploy role**
+ In the `Cloud9-long-string` directory, create a file called `codecatalyst-eks-deploy-policy.json` with the following contents:

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "eks:DescribeCluster",
                  "eks:ListClusters"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```

You have now added three policy documents to your Dev Environment. Your directory structure now looks like this:

```
|— Cloud9-long-string
   |— .c9
   |— codecatalyst-eks-source-repository
      |— Kubernetes
      |— public-html
      |— Dockerfile
   codecatalyst-eks-build-policy.json
   codecatalyst-eks-deploy-policy.json
   codecatalyst-eks-trust-policy.json
```

**4. To add the build policy to AWS**

1. In the Dev Environment terminal, enter:

   ```
   cd /projects
   ```

1. Enter:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-eks-build-policy \
       --policy-document file://codecatalyst-eks-build-policy.json
   ```

1. Press **Enter**.

1. In the command output, note the `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy`. You need this ARN later.

**5. To add the deploy policy to AWS**

1. Enter:

   ```
   aws iam create-policy \
       --policy-name codecatalyst-eks-deploy-policy \
       --policy-document file://codecatalyst-eks-deploy-policy.json
   ```

1. Press **Enter**.

1. In the command output, note the deploy policy's `"arn":` value, for example, `arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy`. You need this ARN later.

**6. To create the build role**

1. Enter: 

   ```
   aws iam create-role \
         --role-name codecatalyst-eks-build-role \
         --assume-role-policy-document file://codecatalyst-eks-trust-policy.json
   ```

1. Press **Enter**.

1. Enter:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-eks-build-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy
   ```

   Where *arn:aws:iam::111122223333:policy/codecatalyst-eks-build-policy* is replaced with the ARN of the build policy you noted earlier.

1. Press **Enter**.

1. At the terminal prompt, enter:

   ```
   aws iam get-role \
         --role-name codecatalyst-eks-build-role
   ```

1. Press **Enter**.

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-eks-build-role`. You need this ARN later.

**7. To create the deploy role**

1. Enter:

   ```
   aws iam create-role \
         --role-name codecatalyst-eks-deploy-role \
         --assume-role-policy-document file://codecatalyst-eks-trust-policy.json
   ```

1. Press **Enter**.

1. Enter:

   ```
   aws iam attach-role-policy \
         --role-name codecatalyst-eks-deploy-role \
         --policy-arn arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy
   ```

   Where *arn:aws:iam::111122223333:policy/codecatalyst-eks-deploy-policy* is replaced with the ARN of the deploy policy you noted earlier.

1. Press **Enter**.

1. Enter:

   ```
   aws iam get-role \
         --role-name codecatalyst-eks-deploy-role
   ```

1. Press **Enter**.

1. Note the role's `"Arn":` value, for example, `arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role`. You need this ARN later.

You have now created build and deploy roles and noted their ARNs.

## Step 6: Add AWS roles to CodeCatalyst
<a name="deploy-tut-eks-import-roles"></a>

In this step, you add the build role (`codecatalyst-eks-build-role`) and deploy role (`codecatalyst-eks-deploy-role`) to the AWS account that you connected to your space. This makes the roles available for use in your workflow.

**To add build and deploy roles to your AWS account**

1. In the CodeCatalyst console, navigate to your space.

1. At the top, choose **Settings**.

1. In the navigation pane, choose **AWS accounts**. A list of accounts appears.

1. In the **Amazon CodeCatalyst display name** column, copy the display name of the AWS account where you created your build and deploy roles. (It might be a number.) You'll need this value later, when creating your workflow.

1. Choose the display name.

1. Choose **Manage roles from AWS management console**.

   The **Add IAM role to Amazon CodeCatalyst space** page appears. You might need to sign in to access the page.

1. Select **Add an existing role you have created in IAM**.

   A drop-down list appears. The list displays the build and deploy roles, and any other IAM roles with a trust policy that includes the `codecatalyst-runner.amazonaws.com` and `codecatalyst.amazonaws.com` service principals.

1. From the drop-down list, add:
   + `codecatalyst-eks-build-role`
   + `codecatalyst-eks-deploy-role`
**Note**  
If you see `The security token included in the request is invalid`, it might be because you do not have the right permissions. To fix this issue, sign out of AWS as sign back in with the AWS account that you used when you created your CodeCatalyst space.

1. Return to the CodeCatalyst console and refresh the page.

   The build and deploy roles should now appear under **IAM roles**.

   These roles are now available for use in CodeCatalyst workflows.

## Step 7: Update the ConfigMap
<a name="deploy-tut-eks-configmap"></a>

You must add the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles) to the Kubernetes `ConfigMap` file to give the **Deploy to Kubernetes cluster** action (in your workflow) the ability to access and interact with your cluster. You can use `eksctl` or `kubectl` to perform this task.

**To configure the Kubernetes ConfigMap file using eksctl**
+ In the Dev Environment terminal, enter: 

  ```
  eksctl create iamidentitymapping --cluster codecatalyst-eks-cluster --arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role --group system:masters --username codecatalyst-eks-deploy-role --region us-west-2
  ```

  Where:
  + *codecatalyst-eks-cluster* is replaced with the cluster name of the Amazon EKS cluster.
  +  *arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role* is replaced with the ARN of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
  +  *codecatalyst-eks-deploy-role* (next to `--username`) is replaced with the name of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
**Note**  
If you decided not to create a deploy role, replace *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).
  +  *us-west-2* is replaced with your Region.

  For details on this command, see [Manage IAM users and roles](https://eksctl.io/usage/iam-identity-mappings/).

  A message similar to the following appears:

  ```
  2023-06-09 00:58:29 [ℹ]  checking arn arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role against entries in the auth ConfigMap
  2023-06-09 00:58:29 [ℹ]  adding identity "arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role" to auth ConfigMap
  ```

**To configure the Kubernetes ConfigMap file using kubectl**

1. In the Dev Environment terminal, enter:

   ```
   kubectl edit configmap -n kube-system aws-auth
   ```

   The ConfigMap file appears on the screen.

1. Add the text in red italics:

   ```
   # Please edit the object below. Lines beginning with a '#' will be ignored,
   # and an empty file will abort the edit. If an error occurs while saving this file will be
   # reopened with the relevant failures.
   #
   apiVersion: v1
   data:
     mapRoles: |
       - groups:
         - system:bootstrappers
         - system:nodes
         rolearn: arn:aws:iam::111122223333:role/eksctl-codecatalyst-eks-cluster-n-NodeInstanceRole-16BC456ME6YR5
         username: system:node:{{EC2PrivateDNSName}}
       - groups:
         - system:masters
         rolearn: arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role
         username: codecatalyst-eks-deploy-role
     mapUsers: |
       []
   kind: ConfigMap
   metadata:
     creationTimestamp: "2023-06-08T19:04:39Z"
     managedFields:
     ...
   ```

   Where:
   +  *arn:aws:iam::111122223333:role/codecatalyst-eks-deploy-role* is replaced with the ARN of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles). 
   +  *codecatalyst-eks-deploy-role* (next to `username:`)is replaced with the name of the deploy role that you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
**Note**  
If you decided not to create a deploy role, replace *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).

   For details, see [Enabling IAM principal access to your cluster](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) in the **Amazon EKS User Guide**.

You have now given the deploy role, and by extension the **Deploy to Amazon EKS** action, `system:masters` permissions to your Kubernetes cluster.

## Step 8: Create and run a workflow
<a name="deploy-tut-eks-workflow"></a>

In this step, you create a workflow that takes your source files, builds them into a Docker image, and then deploys the image into tree pods in your Amazon EKS cluster.

The workflow consists of the following building blocks that run sequentially:
+ A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ A build action (`BuildBackend`) – On trigger, the action builds the Docker image using the Dockerfile and pushes the image to Amazon ECR. The build action also updates the `$REPOSITORY_URI` and `$IMAGE_TAG` variables in the `deployment.yaml` file with the correct values, and then creates an output artifact of this file and any others in the `Kubernetes` folder. In this tutorial, the only file in the `Kubernetes` folder is `deployment.yaml` but you could include more files. The artifact is used as the input for the deploy action, which is next.

  For more information about the build action, see [Building with workflows](build-workflow-actions.md).
+ A deploy action (`DeployToEKS`) – On completion of the build action, the deploy action looks for the output artifact generated by the build action (`Manifests`), and finds the `deployment.yaml` file inside of it. The action then follows the instructions in the `deployment.yaml` file to run three pods—each containing a single 'Hello, World\$1' Docker container—inside your Amazon EKS cluster. 

**To create a workflow**

1. Go to the CodeCatalyst console.

1. Navigate to your project (`codecatalyst-eks-project`).

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose **Create workflow**.

1. For **Source repository**, choose `codecatalyst-eks-source-repository`.

1. For **Branch**, choose `main`.

1. Choose **Create**.

1. Delete the YAML sample code.

1. Add the following YAML code to create a new workflow definition file:
**Note**  
For more information about the workflow definition file, see [Workflow YAML definition](workflow-reference.md).
**Note**  
In the YAML code that follows, you can omit the `Connections:` sections if you want. If you omit these sections, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies of both roles described in [Step 6: Add AWS roles to CodeCatalyst](#deploy-tut-eks-import-roles). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md).

   ```
   Name: codecatalyst-eks-workflow
   SchemaVersion: 1.0
   
   Triggers:
     - Type: PUSH
       Branches:
         - main
   Actions:
     BuildBackend:
       Identifier: aws/build@v1
       Environment:
         Name: codecatalyst-eks-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-eks-build-role
       Inputs:
         Sources:
           - WorkflowSource
         Variables:
           - Name: REPOSITORY_URI
             Value: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo
           - Name: IMAGE_TAG
             Value: ${WorkflowSource.CommitId}
       Configuration:
         Steps:
           #pre_build:
           - Run: echo Logging in to Amazon ECR...
           - Run: aws --version
           - Run: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-west-2.amazonaws.com
           #build:
           - Run: echo Build started on `date`
           - Run: echo Building the Docker image...
           - Run: docker build -t $REPOSITORY_URI:latest .
           - Run: docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
           #post_build:
           - Run: echo Build completed on `date`
           - Run: echo Pushing the Docker images...
           - Run: docker push $REPOSITORY_URI:latest
           - Run: docker push $REPOSITORY_URI:$IMAGE_TAG
           # Replace the variables in deployment.yaml
           - Run: find Kubernetes/ -type f | xargs sed -i "s|\$REPOSITORY_URI|$REPOSITORY_URI|g"
           - Run: find Kubernetes/ -type f | xargs sed -i "s|\$IMAGE_TAG|$IMAGE_TAG|g"
           - Run: cat Kubernetes/*
           # The output artifact will be a zip file that contains Kubernetes manifest files.
       Outputs:
         Artifacts:
           - Name: Manifests
             Files: 
               - "Kubernetes/*"
     DeployToEKS:
       DependsOn: 
         - BuildBackend
       Identifier: aws/kubernetes-deploy@v1
       Environment:
         Name: codecatalyst-eks-environment
         Connections:
           - Name: codecatalyst-account-connection
             Role: codecatalyst-eks-deploy-role
       Inputs:
         Artifacts:
           - Manifests
       Configuration:
         Namespace: default
         Region: us-west-2
         Cluster: codecatalyst-eks-cluster
         Manifests: Kubernetes/
   ```

   In the preceding code, replace:
   + Both instances of *codecatalyst-eks-environment* with the name of the environment you created in [Prerequisites](#deploy-tut-eks-prereqs).
   + Both instances of *codecatalyst-account-connection* with the display name of your account connection. The display name might be a number. For more information, see [Step 6: Add AWS roles to CodeCatalyst](#deploy-tut-eks-import-roles).
   + *codecatalyst-eks-build-role* with the name of the build role you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-eks-image-repo* (in the `Value:` property) with the URI of the Amazon ECR repository you created in [Step 3: Create an Amazon ECR image repository](#deploy-tut-eks-ecr).
   + *111122223333.dkr.ecr.us-west-2.amazonaws.com* (in the `Run: aws ecr` command) with the URI of the Amazon ECR repository without the image suffix (`/codecatalyst-eks-image-repo`).
   + *codecatalyst-eks-deploy-role* with the name of the deploy role you created in [Step 5: Create AWS roles](#deploy-tut-eks-roles).
   + Both instances of *us-west-2* with your AWS Region code. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the *AWS General Reference*.
**Note**  
If you decided not to create build and deploy roles, replace *codecatalyst-eks-build-role* and *codecatalyst-eks-deploy-role* with the name of the `CodeCatalystWorkflowDevelopmentRole-spaceName` role. For more information about this role, see [Step 5: Create AWS roles](#deploy-tut-eks-roles).

1. (Optional) Choose **Validate** to make sure that the YAML code is valid before committing.

1. Choose **Commit**.

1. In the **Commit workflow** dialog box, enter the following:

   1. For **Commit message**, remove the text and enter:

      ```
      Add first workflow
      ```

   1. For **Repository**, choose `codecatalyst-eks-source-repository`.

   1. For **Branch name**, choose main.

   1. Choose **Commit**.

   You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `workflow.yaml` file to your source repository, the trigger started the workflow run.

**To view the workflow run progress**

1. In the navigation pane of the CodeCatalyst console, choose **CI/CD**, and then choose **Workflows**.

1. Choose the workflow you just created, `codecatalyst-eks-workflow`.

1. Choose **BuildBackend** to see the build progress.

1. Choose **DeployToEKS** to see the deployment progress.

   For more information about viewing run details, see [Viewing workflow run status and details](workflows-view-run.md).

**To verify the deployment**

1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

1. On the left, near the bottom, choose **Load Balancers**.

1. Select the load balancer that was created as part of your Kubernetes deployment. If you're not sure which load balancer to choose, look for the following tags under the **Tags** tab:
   + `kubernetes.io/service-name`
   + `kubernetes.io/cluster/ekstutorialcluster`

1. With the correct load balancer selected, choose the **Description** tab.

1. Copy and paste the **DNS name** value into your browser's address bar.

   The 'Hello, World\$1' webpage appears in your browser, indicating that you successfully deployed your application.

## Step 9: Make a change to your source files
<a name="deploy-tut-eks-change"></a>

In this section, you make a change to the `index.html` file in your source repository. This change causes the workflow to build a new Docker image, tag it with a commit ID, push it to Amazon ECR, and deploy it to Amazon ECS. 

**To change the index.html**

1. Go to your Dev Environment.

1. At the terminal prompt, change to your source repository:

   ```
   cd /projects/codecatalyst-eks-source-repository
   ```

1.  Pull the latest workflow changes:

   ```
   git pull
   ```

1. Open `codecatalyst-eks-source-repository/public-html/index.html`.

1. On line 14, change the `Hello, World!` text to `Tutorial complete!`.

1. Add, commit, and push:

   ```
   git add .
   git commit -m "update index.html title"
   git push
   ```

   A workflow run starts automatically.

1. (Optional) Enter:

   ```
   git show HEAD
   ```

   Note the commit ID for the `index.html` change. This commit ID will be tagged to the Docker image that will be deployed by the workflow run that you just started.

1. Watch the deployment progress:

   1. In the CodeCatalyst console, in the navigation pane, choose **CI/CD**, and then choose **Workflows**.

   1. Choose `codecatalyst-eks-workflow` to view the latest run.

   1. Choose **BuildBackend**, and **DeployToEKS** to see the workflow run progress.

1. Verify that your application was updated, as follows:

   1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

   1. On the left, near the bottom, choose **Load Balancers**.

   1. Select the load balancer that was created as part of your Kubernetes deployment.

   1. Copy and paste the **DNS name** value into your browser's address bar.

      The 'Tutorial Complete\$1' webpage appears in your browser, indicating that you successfully deployed a new revision of your application.

1. (Optional) In AWS, switch to the Amazon ECR console and verify that the new Docker image was tagged with the commit ID from step 7 of this procedure.

## Clean up
<a name="deploy-tut-eks-cleanup"></a>

You should clean up your environment so that you're not charged unnecessarily for the storage and compute resources used by this tutorial.

**To clean up**

1. Delete your cluster:

   1. In the Dev Environment terminal, enter:

     ```
     eksctl delete cluster --region=us-west-2 --name=codecatalyst-eks-cluster
     ```

     Where:
     + *us-west-2* is replaced with your Region.
     + *codecatalyst-eks-cluster* is replaced with the name of the cluster you created.

     After 5-10 minutes, the cluster and associated resources are deleted, including but not limited to CloudFormation stacks, nodes groups (in Amazon EC2), and load balancers.
**Important**  
If the `eksctl delete cluster` command doesn't work, you may need to refresh your AWS credentials or your `kubectl` credentials. If you're not sure which credentials to refresh, refresh the AWS credentials first. To refresh your AWS credentials, see [How do I fix "Unable to locate credentials" and "ExpiredToken" errors?](troubleshooting-workflows.md#troubleshooting-workflows-auth-errors-eks). To refresh your `kubectl` credentials, see [How do I fix "Unable to connect to the server" errors?](troubleshooting-workflows.md#troubleshooting-workflows-unable-connect-eks).

1. In the AWS console, clean up as follows:

   1. In Amazon ECR, delete `codecatalyst-eks-image-repo`.

   1. In IAM Identity Center, delete:

      1. `codecatalyst-eks-user`

      1. `codecatalyst-eks-permission-set`

   1. In IAM, delete:
      + `codecatalyst-eks-build-role`
      + `codecatalyst-eks-deploy-role`
      + `codecatalyst-eks-build-policy`
      + `codecatalyst-eks-deploy-policy`

1. In the CodeCatalyst console, clean up as follows:

   1. Delete `codecatalyst-eks-workflow`.

   1. Delete `codecatalyst-eks-environment`.

   1. Delete `codecatalyst-eks-source-repository`.

   1. Delete your Dev Environment.

   1. Delete `codecatalyst-eks-project`.

In this tutorial, you learned how to deploy an application to an Amazon EKS service using a CodeCatalyst workflow and a **Deploy to Kubernetes cluster** action.

# Adding the 'Deploy to Kubernetes cluster' action
<a name="deploy-action-eks-adding"></a>

Use the following instructions to add the **Deploy to Kubernetes cluster** action to your workflow. 

**Before you begin**

Before you add the **Deploy to Kubernetes cluster** action to your workflow, you must have the following prepared:

**Tip**  
To set up these prerequisites quickly, follow the instructions in [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md).
+ A Kubernetes cluster in Amazon EKS. For information about clusters, see [Amazon EKS clusters](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) in the **Amazon EKS User Guide**.
+ At least one Dockerfile that describes how to assemble your application into a Docker image. For more information about Dockerfiles, see the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).
+ At least one Kubernetes manifest file, which is called a *configuration file* or *configuration* in the Kubernetes documentation. For more information, see [Managing resources](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) in the Kubernetes documentation.
+ An IAM role that gives the **Deploy to Kubernetes cluster** action the ability to access and interact with your Amazon EKS cluster. For more information, see the [Role](deploy-action-ref-eks.md#deploy.action.eks.environment.connections.role) topic in the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md).

  After creating this role, you must add it to:
  + Your Kubernetes ConfigMap file. To learn how to add a role to a ConfigMap file, see [Enabling IAM principal access to your cluster](https://docs.aws.amazon.com/eks/latest/userguide/add-user-role.html) in the **Amazon EKS User Guide**.
  + CodeCatalyst. To learn how to add an IAM role to CodeCatalyst, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
+ A CodeCatalyst space, project, and environment. The space and environment must both be connected to the AWS account into which you will be deploying your application. For more information, see [Creating a space](spaces-create.md), [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty), and [Deploying into AWS accounts and VPCs](deploy-environments.md).
+ A source repository supported by CodeCatalyst. The repository stores your application source files, Dockerfiles, and Kubernetes manifests. For more information, see [Store and collaborate on code with source repositories in CodeCatalystStore and collaborate on code with source repositories](source.md).

------
#### [ Visual ]

**To add the 'Deploy to Kubernetes cluster' action using the visual editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **Visual**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Kubernetes cluster** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Kubernetes cluster**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md). This reference provides detailed information about each field (and corresponding YAML property value) as it appears in both the YAML and visual editors.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------
#### [ YAML ]

**To add the 'Deploy to Kubernetes cluster' action using the YAML editor**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Choose your project.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status.

1. Choose **Edit**.

1. Choose **YAML**.

1. At the top-left, choose **\$1 Actions** to open the action catalog.

1. From the drop-down list, choose **Amazon CodeCatalyst**.

1. Search for the **Deploy to Kubernetes cluster** action, and do one of the following:
   + Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.

     Or
   + Choose **Deploy to Kubernetes cluster**. The action details dialog box appears. On this dialog box:
     + (Optional) Choose **Download** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
     + Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.

1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['Deploy to Kubernetes cluster' action YAML](deploy-action-ref-eks.md).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, enter a commit message, and choose **Commit** again.

------

# 'Deploy to Kubernetes cluster' variables
<a name="deploy-action-eks-variables"></a>

The **Deploy to Kubernetes cluster** action produces and sets the following variables at run time. These are known as *predefined variables*.

For information about referencing these variables in a workflow, see [Using predefined variables](workflows-using-predefined-variables.md).


| Key | Value | 
| --- | --- | 
|  cluster  |  The Amazon.com Resource Name (ARN) of the of the Amazon EKS cluster that was deployed to during the workflow run. Example: `arn:aws:eks:us-west-2:111122223333:cluster/codecatalyst-eks-cluster`  | 
|  deployment-platform  |  The name of the deployment platform. Hardcoded to `AWS:EKS`.  | 
|  metadata  |  Reserved. JSON-formatted metadata related to the cluster deployed during the workflow run.  | 
|  namespace  |  The Kubernetes namespace into which the cluster was deployed. Example: `default`  | 
|  resources  |  Reserved. JSON-formatted metadata related to the resources deployed during the workflow run.  | 
|  server  |  The name of the API server endpoint that you can use to communicate with your cluster using management tools such as `kubectl`. For more information about the API service endpoint, see [Amazon EKS cluster endpoint access control](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) in the **Amazon EKS User Guide**. Example: `https://random-string.gr7.us-west-2.eks.amazonaws.com`  | 

# 'Deploy to Kubernetes cluster' action YAML
<a name="deploy-action-ref-eks"></a>

The following is the YAML definition of the **Deploy to Kubernetes cluster** action. To learn how to use this action, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md).

This action definition exists as a section within a broader workflow definition file. For more information about this file, see [Workflow YAML definition](workflow-reference.md).

**Note**  
Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use **Ctrl\$1F**. The element will be listed with its associated YAML property.

```
# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.   
  DeployToKubernetesCluster\$1nn: 
    Identifier: aws/kubernetes-deploy@v1
    DependsOn:
      - build-action
    Compute:  
        - Type: EC2 | Lambda
        - Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: DeployToEKS
    Inputs:
      # Specify a source or an artifact, but not both.
      Sources:
        - source-name-1
      Artifacts:
        - manifest-artifact
    Configuration:
      Namespace: namespace
      Region: us-east-1 
      Cluster: eks-cluster
      Manifests: manifest-path
```

## DeployToKubernetesCluster
<a name="deploy.action.eks.name"></a>

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (\$1). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Default: `DeployToKubernetesCluster_nn`.

Corresponding UI: Configuration tab/**Action display name**

## Identifier
<a name="deploy.action.eks.identifier"></a>

(*DeployToKubernetesCluster*/**Identifier**)

(Required)

Identifies the action. Do not change this property unless you want to change the version. For more information, see [Specifying the action version to use](workflows-action-versions.md).

Default: `aws/kubernetes-deploy@v1`.

Corresponding UI: Workflow diagram/DeployToKubernetesCluster\$1nn/**aws/kubernetes-deploy@v1** label

## DependsOn
<a name="deploy.action.eks.dependson"></a>

(*DeployToKubernetesCluster*/**DependsOn**)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see [Sequencing actions](workflows-depends-on.md).

Corresponding UI: Inputs tab/**Depends on - optional**

## Compute
<a name="deploy.action.eks.computename"></a>

(*DeployToKubernetesCluster*/**Compute**)

(Optional)

The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. At the workflow level, you can also run multiple actions on the same instance. For more information, see [Sharing compute across actions](compute-sharing.md).

Corresponding UI: *none*

## Type
<a name="deploy.action.eks.computetype"></a>

(*DeployToKubernetesCluster*/Compute/**Type**)

(Required if [Compute](#deploy.action.eks.computename) is included)

The type of compute engine. You can use one of the following values:
+ **EC2** (visual editor) or `EC2` (YAML editor)

  Optimized for flexibility during action runs.
+ **Lambda** (visual editor) or `Lambda` (YAML editor)

  Optimized action start-up speeds.

For more information about compute types, see [Compute types](workflows-working-compute.md#compute.types).

Corresponding UI: Configuration tab/Advanced - optional/**Compute type**

## Fleet
<a name="deploy.action.eks.computefleet"></a>

(*DeployToKubernetesCluster*/Compute/**Fleet**)

(Optional)

Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: `Linux.x86-64.Large`, `Linux.x86-64.XLarge`. For more information about on-demand fleets, see [On-demand fleet properties](workflows-working-compute.md#compute.on-demand).

With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see [Provisioned fleet properties](workflows-working-compute.md#compute.provisioned-fleets).

If `Fleet` is omitted, the default is `Linux.x86-64.Large`.

Corresponding UI: Configuration tab/Advanced - optional/**Compute fleet**

## Timeout
<a name="deploy.action.eks.timeout"></a>

(*DeployToKubernetesCluster*/**Timeout**)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in [Quotas for workflows in CodeCatalyst](workflows-quotas.md). The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/**Timeout - optional **

## Environment
<a name="deploy.action.eks.environment"></a>

(*DeployToKubernetesCluster*/**Environment**)

(Required)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the [Amazon VPC connection](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) to connect to the Amazon VPC.

**Note**  
If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see [Changing the IAM role of an action](deploy-environments-switch-role.md).

For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: Configuration tab/**Environment**

## Name
<a name="deploy.action.eks.environment.name"></a>

(*DeployToKubernetesCluster*/Environment/**Name**)

(Required if [Environment](#deploy.action.eks.environment) is included)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/**Environment**

## Connections
<a name="deploy.action.eks.environment.connections"></a>

(*DeployToKubernetesCluster*/Environment/**Connections**)

(Optional in newer versions of the action; required in older versions)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under `Environment`.

If you do not specify an account connection:
+ The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see [Creating an environment](deploy-environments-creating-environment.md).
+ The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the **Role** property in the action's YAML definition documentation.

For more information about account connections, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md).

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Name
<a name="deploy.action.eks.environment.connections.name"></a>

(*DeployToKubernetesCluster*/Environment/Connections/**Name**)

(Optional)

Specify the name of the account connection.

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**AWS account connection**

## Role
<a name="deploy.action.eks.environment.connections.role"></a>

(*DeployToKubernetesCluster*/Environment/Connections/**Role**)

(Required if [Connections](#deploy.action.eks.environment.connections) is included)

Specify the name of the IAM role that the **Deploy to Kubernetes cluster ** action uses to access AWS. Make sure that you have [added the role to your CodeCatalyst space](ipa-connect-account-addroles.md), and that the role includes the following policies.

If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.
+ The following permissions policy:
**Warning**  
Limit the permissions to those shown in the following policy. Using a role with broader permissions might pose a security risk.

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "eks:DescribeCluster",
                  "eks:ListClusters"
              ],
              "Resource": "*"
          }
      ]
  }
  ```

------
**Note**  
The first time the role is used, use the following wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.  

  ```
  "Resource": "*"
  ```
+ The following custom trust policy:

Make sure that this role is added to:
+ Your account connection. To learn more about adding an IAM role to an account connection, see [Adding IAM roles to account connections](ipa-connect-account-addroles.md).
+ Your Kubernetes ConfigMap. To learn more about adding an IAM role to a ConfigMap, see [Manage IAM users and roles](https://eksctl.io/usage/iam-identity-mappings/) in the `eksctl` documentation.

**Tip**  
See also [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md) for instructions on adding am IAM role to an account connection and ConfigMap.

**Note**  
You can use the `CodeCatalystWorkflowDevelopmentRole-spaceName` role with this action, if you'd like. For more information about this role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create). Understand that the `CodeCatalystWorkflowDevelopmentRole-spaceName` role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern. 

Corresponding UI: One of the following depending on the action version:
+ (Newer versions) Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role**
+ (Older versions) Configuration tab/'Environment/account/role'/**Role**

## Inputs
<a name="deploy.action.eks.inputs"></a>

(*DeployToKubernetesCluster*/**Inputs**)

(Required if [Connections](#deploy.action.eks.environment.connections) is included)

The `Inputs` section defines the data that the `DeployToKubernetesCluster` needs during a workflow run.

**Note**  
Only one input (either a source or an artifact) is allowed per **Deploy to Amazon EKS** action.

Corresponding UI: **Inputs** tab

## Sources
<a name="deploy.action.eks.inputs.sources"></a>

(*DeployToKubernetesCluster*/Inputs/**Sources**)

(Required if your manifest file is stored in a source repository)

If your Kubernetes manifest file or files are stored in a source repository, specify the label of that source repository. Currently, the only supported label is `WorkflowSource`.

If your manifest files are not contained within a source repository, they must reside in an artifact generated by another action.

For more information about sources, see [Connecting source repositories to workflows](workflows-sources.md).

Corresponding UI: Inputs tab/**Sources - optional**

## Artifacts - input
<a name="deploy.action.eks.inputs.artifacts"></a>

(*DeployToKubernetesCluster*/Inputs/**Artifacts**)

(Required if your manifest file is stored in an [output artifact](workflows-working-artifacts-output.md) from a previous action)

If the Kubernetes manifest file or files are contained in an artifact generated by a previous action, specify that artifact here. If your manifest files are not contained within an artifact, they must reside in your source repository.

For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md).

Corresponding UI: Configuration tab/**Artifacts - optional**

## Configuration
<a name="deploy.action.eks.configuration"></a>

(*DeployToKubernetesCluster*/**Configuration**)

(Required)

A section where you can define the configuration properties of the action.

Corresponding UI: **Configuration** tab

## Namespace
<a name="deploy.action.eks.namespace"></a>

(*DeployToKubernetesCluster*/Configuration/**Namespace**)

(Optional)

Specify the Kubernetes namespace into which your Kubernetes application will be deployed. Use `default` if you are not using namespaces with your cluster. For more information on namespaces, see [Subdividing your cluster using Kubernetes namespaces](https://kubernetes.io/docs/tasks/administer-cluster/namespaces/#subdividing-your-cluster-using-kubernetes-namespaces) in the Kubernetes documentation.

If you omit the namespace, a value of `default` is used.

Corresponding UI: Configuration tab/**Namespace**

## Region
<a name="deploy.action.eks.region"></a>

(*DeployToKubernetesCluster*/Configuration/**Region**)

(Required)

Specify the AWS Region where your Amazon EKS cluster and service reside. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes) in the *AWS General Reference*.

Corresponding UI: Configuration tab/**Region**

## Cluster
<a name="deploy.action.eks.cluster"></a>

(*DeployToKubernetesCluster*/Configuration/**Cluster**)

(Required)

Specify the name of an existing Amazon EKS cluster. The **Deploy to Kubernetes cluster** action will deploy your containerized application into this cluster. For more information about Amazon EKS clusters, see [Clusters](https://docs.aws.amazon.com/eks/latest/userguide/clusters.html) in the **Amazon EKS User Guide**.

Corresponding UI: Configuration tab/**Cluster**

## Manifests
<a name="deploy.action.eks.manifest"></a>

(*DeployToKubernetesCluster*/Configuration/**Manifests**)

(Required)

Specify the path to your YAML-formatted Kubernetes manifest file(s), which are called *configuration files*, *config files*, or simply, *configurations* in the Kubernetes documentation.

If you're using multiple manifest files, place them in a single folder and reference that folder. Manifest files are processed alphanumerically by Kubernetes, so make sure to prefix file names with increasing numbers or letters to control the processing order. For example:

`00-namespace.yaml`

`01-deployment.yaml`

If your manifest files reside in your source repository, the path is relative to the source repository root folder. If the files reside in an artifact from a previous workflow action, the path is relative to the artifact root folder. 

Examples:

`Manifests/`

`deployment.yaml`

`my-deployment.yml`

Do not use wildcards (`*`).

**Note**  
[Helm charts](https://helm.sh/docs/topics/charts/) and [kustomization files](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/) are not supported.

For more information about manifest files, see [Organizing resource configurations](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#organizing-resource-configurations) in the Kubernetes documentation.

Corresponding UI: Configuration tab/**Manifests**