> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/aws-eks

An orb for working with Amazon Elastic Container Service for Kubernetes (Amazon EKS).


## Commands

### create_cluster

Creates an EKS cluster and required resources (e.g. VPC) using the eksctl tool.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `asg_access` | boolean | false | Set to true to enable IAM policy for cluster-autoscaler.
 |
| `aws_max_polling_wait_time` | string | 20m0s | Max wait time in any AWS polling operations
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | AWS region that the EKS cluster will be created in.
 |
| `cfn_role_arn` | string |  | Specify an IAM role to be used by CloudFormation to call AWS API on your behalf
 |
| `cluster_name` | string |  | Name of the EKS cluster to be created
 |
| `config_file` | string |  | Use this to specify a file if you wish to load configuration from it.
 |
| `external_dns_access` | boolean | false | Set to true to enable IAM policy for external-dns.
 |
| `fargate` | boolean | false | Specify the node to run on fargate.
 |
| `full_ecr_access` | boolean | false | Set to true to enable full access to ECR.
 |
| `kubectl_version` | string | v1.36.1 | Version of kubectl to install
 |
| `kubernetes_version` | string |  | Specify a version of Kubernetes that is supported by eksctl.
If no value is specified, the version that eksctl defaults to will be used.
 |
| `max_pods_per_node` | integer | -1 | Sets the maximum number of pods per node, if a number other than -1 is set as the value.
Otherwise the maximum will be automatically set.
 |
| `no_output_timeout` | string | 45m | Elapsed time that the cluster creation command can run on CircleCI without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `node_ami` | string |  | Specify this in advanced use cases only.
Check the documentation for the --node_ami flag of eksctl for more details.
 |
| `node_ami_family` | string |  | Specify this in advanced use cases only.
Check the documentation for the --node_ami_family flag of eksctl for more details.
 |
| `node_labels` | string |  | Extra labels to add when registering the nodes in the nodegroup, e.g. "partition=backend,nodeclass=hugememory"
 |
| `node_private_networking` | boolean | false | Set to true to make nodegroup networking private.
 |
| `node_security_groups` | string |  | Specify a comma-delimited list of security groups to be attached to nodes, for allowing
extra ingress/egress access from/to pods.
 |
| `node_type` | string |  | Set this to specify a node instance type for the node group.
 |
| `node_volume_size` | integer | -1 | Sets the node volume size in GB, if a number other than -1 is set as the value.
 |
| `node_volume_type` | string |  | Specify the node volume type.
 |
| `node_zones` | string |  | Specify availability zones for the nodes e.g. us-east-1a,us-east-1b,us-east-1d
Zones will be inherited from the cluster if unspecified.
 |
| `nodegroup_name` | string |  | Set this to specify a name for the nodegroup.
If unspecified, it will be generated.
 |
| `nodes` | integer | -1 | Sets the total number of nodes (for a static Auto Scaling Group), if a number other than -1 is set as the value.
Otherwise the default as determined by eksctl will be used.
 |
| `nodes_max` | integer | -1 | Sets the maximum number of nodes in the Auto Scaling Group, if a number other than -1 is set as the value.
Otherwise the default as determined by eksctl will be used.
 |
| `nodes_min` | integer | -1 | Sets the minimum number of nodes in the Auto Scaling Group, if a number other than -1 is set as the value.
Otherwise the default as determined by eksctl will be used.
 |
| `show_eksctl_command` | boolean | false | Whether to show the eksctl command used.
 |
| `skip_kubectl_install` | boolean | false | Whether to skip the installation of kubectl.
 |
| `ssh_access` | boolean | false | Control SSH access for nodes
 |
| `ssh_public_key` | string |  | SSH public key to use for nodes (import from local path, or use existing EC2 key pair which
must not resolve to a local file path)
e.g. my_eks_node_id.pub
"~/.ssh/id_rsa.pub" will be taken as the path if a value is not specified.
 |
| `tags` | string |  | A list of key-value pairs used to tag the AWS resources (e.g. "Owner=John Doe,Team=Some Team")
 |
| `verbose` | integer | 3 | Set a value from 0 to 5 to control the verbosity level of the log output (the higher, the more verbose).
Use 0 to silence, 4 for debugging and 5 for debugging with AWS debug logging.
The logging verbosity level is set to 3 by default.
When set to 4 and above, verbose details of AWS resources will be displayed in the log output.
When set to 5, sensitive information such as credentials may be displayed in the log output.
 |
| `vpc_cidr` | string |  | Specify global CIDR to use for VPC.
e.g. 192.168.0.0/16
 |
| `vpc_from_kops_cluster` | string |  | Specify this to re-use a VPC from a given kops cluster.
e.g. cluster-1.k8s.local
 |
| `vpc_private_subnets` | string |  | Specify this to re-use private subnets of an existing VPC.
e.g. subnet-0ff156e0c4a6d300c,subnet-0426fb4a607393184
 |
| `vpc_public_subnets` | string |  | Specify this to re-use public subnets of an existing VPC.
e.g. subnet-0ff156e0c4a6d300c,subnet-0426fb4a607393184
 |
| `without_nodegroup` | boolean | false | Set to true to avoid creating initial nodegroup.
 |
| `zones` | string |  | The AWS availability zones to be used  e.g. us-east-1a,us-east-1b,us-east-1d
If no value is specified, the availability zones will be auto-selected.
 |

### delete_cluster

Deletes the EKS cluster and resources that were created for it.
The cluster must have been created with the create_cluster command of the orb.
It is recommended to delete any kubernetes resources that were deployed to the
cluster (e.g. resources involving an AWS Elastic Load Balancer)
before running the delete_cluster command, so that resources can be fully
removed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `aws_max_polling_wait_time` | string | 20m0s | Max wait time in any AWS polling operations
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | AWS region that the EKS cluster will be created in.
If no value is specified, the cluster will be created in the us-west-2 region.
 |
| `cfn_role_arn` | string |  | Specify an IAM role to be used by CloudFormation to call AWS API on your behalf
 |
| `cluster_name` | string |  | Name of the EKS cluster
 |
| `config_file` | string |  | Use this to specify a file if you wish to load configuration from it.
 |
| `no_output_timeout` | string | 30m | Elapsed time that the cluster creation command can run without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `show_eksctl_command` | boolean | false | Whether to show the eksctl command used.
 |
| `verbose` | integer | 3 | Set a value from 0 to 5 to control the verbosity level of the log output (the higher, the more verbose).
Use 0 to silence, 4 for debugging and 5 for debugging with AWS debug logging.
The logging verbosity level is set to 3 by default.
When set to 4 and above, verbose details of AWS resources will be displayed in the log output.
When set to 5, sensitive information such as credentials may be displayed in the log output.
 |
| `wait` | boolean | false | Whether to wait for deletion of all resources before exiting
 |

### install_aws_iam_authenticator

Install the AWS IAM Authenticator for Kubernetes
Requirements: curl, amd64 architecture


| Parameter | Type | Default | Description |
|---|---|---|---|
| `release_tag` | string |  | Use this to specify a tag to select which published release of the AWS IAM Authenticator,
as listed on https://github.com/kubernetes-sigs/aws-iam-authenticator/releases,
to install. If no value is specified, the latest release will be installed.
Note: Release versions earlier than v0.3.0 cannot be specified. Also,
pre or alpha releases cannot be specified.
 |

### setup

Install the Amazon eksctl command line utility.  This command should be ran before invoking the eskctl cli.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | Specify the full semver versioned tag to use.
The latest version will be installed by default if none is specified.
 |

### update_kubeconfig_with_authenticator

Allows the stock kubectl client to work with Amazon EKS.
Installs the AWS IAM Authenticator for Kubernetes and
updates the kubectl configuration file to use the AWS IAM Authenticator.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `authenticator_release_tag` | string |  | Specifies which release_tag version of the authenticator to install.
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | The AWS region that the cluster is in. If not specified, the configured default
region for your AWS CLI installation will be used.
 |
| `cluster_authentication_role_arn` | string |  | To assume a role for cluster authentication, specify an IAM role ARN with
this option. For example, if you created a cluster while assuming an IAM
role, then you must also assume that role to connect to the cluster the
first time.
 |
| `cluster_context_alias` | string |  | Alias for the cluster context name. If a value is not specified,
the cluster context name will be set to match the cluster ARN.
 |
| `cluster_name` | string |  | The name of the cluster for which to create a kubeconfig entry.
 |
| `dry_run` | enum |  | Print the merged kubeconfig to stdout instead of writing it to file.
 |
| `install_kubectl` | boolean | false | Whether to install kubectl
 |
| `kubeconfig_file_path` | string |  | Specifies a kubeconfig file to append the configuration details to.
By default, the configuration is written to the first file path in the
KUBECONFIG environment variable (if it is set) or the default kubeconfig
path (.kube/config) in your home directory.
 |
| `kubectl_version` | string | v1.36.1 | Version of kubectl to install
 |
| `verbose` | boolean | false | Print more detailed output when writing to the kubeconfig file.
 |

## Jobs

### create_cluster

Creates an EKS cluster and required resources (e.g. VPC) using the eksctl tool.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `authenticator_release_tag` | string |  | Specifies which release_tag version of the authenticator to install.
 |
| `aws_max_polling_wait_time` | string | 20m0s | Max wait time in any AWS polling operations
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | AWS region that the EKS cluster will be created in.
 |
| `cluster_name` | string |  | Name of the EKS cluster to be created
 |
| `no_output_timeout` | string | 45m | Elapsed time that the cluster creation command can run on CircleCI without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `show_eksctl_command` | boolean | false | Whether to show the eksctl command used.
 |
| `ssh_access` | boolean | false | Control SSH access for nodes
 |
| `ssh_public_key` | string |  | SSH public key to use for nodes (import from local path, or use existing EC2 key pair which
must not resolve to a local file path)
e.g. my_eks_node_id.pub
"~/.ssh/id_rsa.pub" will be taken as the path if a value is not specified.
 |
| `tag` | string | 3.10 | Version of the CircleCI Python convenience image to use. For full list,
see https://hub.docker.com/r/cimg/python/tags
A version of Python supported by the AWS CLI is required.
 |
| `tags` | string |  | A list of key-value pairs used to tag the AWS resources (e.g. "Owner=John Doe,Team=Some Team")
 |
| `verbose` | integer | 3 | Set a value from 0 to 5 to control the verbosity level of the log output (the higher, the more verbose).
Use 0 to silence, 4 for debugging and 5 for debugging with AWS debug logging.
The logging verbosity level is set to 3 by default.
When set to 4 and above, verbose details of AWS resources will be displayed in the log output.
When set to 5, sensitive information such as credentials may be displayed in the log output.
 |

### delete_cluster

Deletes an EKS cluster together with the associated VPC resources on AWS,
using the eksctl tool. The cluster should have been created with eksctl
as well.
It is recommended to delete any kubernetes resources that were deployed to the
cluster (e.g. resources involving an AWS Elastic Load Balancer)
before running the delete_cluster command, so that resources can be fully
removed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `authenticator_release_tag` | string |  | Specifies which release_tag version of the authenticator to install.
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | AWS region that the EKS cluster is in.
 |
| `cluster_name` | string |  | The name of the EKS cluster to be deleted.
 |
| `kubectl_version` | string | v1.22.0 | Version of kubectl to install
 |
| `no_output_timeout` | string | 30m | Elapsed time that the cluster creation command can run without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s” (default: 20 minutes)
 |
| `tag` | string | 3.10 | Version of the CircleCI Python convenience image to use. For full list,
see https://hub.docker.com/r/cimg/python/tags
A version of Python supported by the AWS CLI is required.
 |
| `verbose` | integer | 3 | Set a value from 0 to 5 to control the verbosity level of the log output (the higher, the more verbose).
Use 0 to silence, 4 for debugging and 5 for debugging with AWS debug logging.
The logging verbosity level is set to 3 by default.
When set to 4 and above, verbose details of AWS resources will be displayed in the log output.
When set to 5, sensitive information such as credentials may be displayed in the log output.
 |
| `wait` | boolean | false | Whether to wait for deletion of all resources before exiting
 |

### update_container_image

Updates the container image(s) of a resource on EKS.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `authenticator_release_tag` | string |  | Specifies which release_tag version of the authenticator to install.
 |
| `aws_profile` | string |  | The AWS profile to be used. If not specified, the configured default
profile for your AWS CLI installation will be used.
 |
| `aws_region` | string |  | AWS region that the EKS cluster is in.
 |
| `cluster_name` | string |  | The name of the EKS cluster.
 |
| `container_image_updates` | string |  | Specify a list of container image updates
(space-delimited name value pairs in the form
CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N)
to be applied to the resource via `kubectl set image`.
e.g. "busybox=busybox nginx=nginx:1.9.1"
 |
| `get_rollout_status` | boolean | false | Get the status of the rollout.
This can only be used for resource types that are valid
for usage with `kubectl rollout` subcommands.
 |
| `kubectl_version` | string | v1.36.1 | Version of kubectl to install
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `pinned_revision_to_watch` | string |  | Pin a specific revision to be watched and abort watching if it is rolled
over by another revision.
Only effective if get_rollout_status is set to true.
 |
| `resource_name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
Either resource-file-path or resource_name need to be specified.
This is required if get_rollout_status is set to true.
 |
| `show_kubectl_command` | boolean | false | Whether to show the kubectl command used.
 |
| `tag` | string | 3.10 | Version of the CircleCI Python convenience image to use. For full list,
see https://hub.docker.com/r/cimg/python/tags
A version of Python supported by the AWS CLI is required.
 |
| `watch_rollout_status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
Only effective if get_rollout_status is set to true.
 |
| `watch_timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h).
Only effective if get_rollout_status is set to true.
 |

## Examples

### create_eks_cluster

Create an eks cluster together with the required VPC-related resources, test it, and tear it down using OIDC authentication.
Import the aws-cli orb and authenticate using the aws-cli/setup command with a valid role_arn for OIDC authentication.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@3.1
  aws-eks: circleci/aws-eks@3.0
  kubernetes: circleci/kubernetes@1.3
jobs:
  test-cluster:
    docker:
      - image: cimg/python:3.11
    parameters:
      cluster_name:
        description: |
          Name of the EKS cluster
        type: string
    steps:
      - kubernetes/install:
          kubectl_version: v1.36.1
      - aws-eks/update_kubeconfig_with_authenticator:
          cluster_name: << parameters.cluster_name >>
      - run:
          command: |
            kubectl get services
          name: Test cluster
workflows:
  deployment:
    jobs:
      - aws-eks/create_cluster:
          auth:
            - aws-cli/setup:
                profile: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_OIDC_ROLE
          aws_profile: OIDC-USER
          cluster_name: my-eks-demo
          context: OIDC-CONTEXT
      - test-cluster:
          cluster_name: my-eks-demo
          requires:
            - aws-eks/create_cluster
      - aws-eks/delete_cluster:
          auth:
            - aws-cli/setup:
                profile: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_OIDC_ROLE
          aws_profile: OIDC-USER
          cluster_name: my-eks-demo
          context: OIDC-CONTEXT
          requires:
            - test-cluster
```

### create_k8s_deployment

Create a kubernetes deployment.


```yaml
version: '2.1'
orbs:
  aws-eks: circleci/aws-eks@<<pipeline.parameters.dev-orb-version>>
  kubernetes: circleci/kubernetes@1.3
jobs:
  create-deployment:
    docker:
      - image: cimg/python:3.10
    parameters:
      cluster_name:
        description: |
          Name of the EKS cluster
        type: string
    steps:
      - checkout
      - aws-eks/update_kubeconfig_with_authenticator:
          cluster_name: << parameters.cluster_name >>
          install_kubectl: true
      - kubernetes/create_or_update_resource:
          get_rollout_status: true
          resource_file_path: tests/nginx-deployment/deployment.yaml
          resource_name: deployment/nginx-deployment
workflows:
  deployment:
    jobs:
      - aws-eks/create_cluster:
          cluster_name: eks-demo-deployment
      - create-deployment:
          cluster_name: eks-demo-deployment
          requires:
            - aws-eks/create_cluster
      - aws-eks/update_container_image:
          cluster_name: eks-demo-deployment
          container_image_updates: nginx=nginx:1.9.1
          post-steps:
            - kubernetes/delete_resource:
                resource_names: nginx-deployment
                resource_types: deployment
                wait: true
          requires:
            - create-deployment
          resource_name: deployment/nginx-deployment
      - aws-eks/delete_cluster:
          cluster_name: eks-demo-deployment
          requires:
            - aws-eks/update_container_image
```