---
title: "Deploy Anyscale on Amazon EKS (cloud register)"
description: "Deploy an Anyscale cloud on Amazon EKS using Terraform and the anyscale cloud register command."
---

# Deploy Anyscale on Amazon EKS (cloud register)

This page describes how to deploy an Anyscale cloud on EKS using `anyscale cloud register`. This path gives you full control over cluster resources and networking. You provision and configure all resources yourself, then register the cloud with Anyscale.

:::tip
For a faster, automated setup, use `anyscale cloud setup` instead. See [Set up Anyscale on EKS](/clouds/aws/setup-eks.md).
:::

Complete the following steps to configure and deploy a new Anyscale cloud on EKS.

## 1\. Install the Anyscale CLI

```bash
pip install -U anyscale
anyscale login # authenticate
```

## 2\. Authenticate the AWS CLI

Set up your AWS credentials locally if you haven't done so before. See the [AWS configuration guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new-command).

```bash
aws configure
```

:::note
Before you continue, make sure your AWS credentials have the following permissions:

-   Launch EC2 instances in the AWS region you plan to use.
-   Manage these resources: VPC, subnets, Security Group, IAM, and S3.

See [Manage Anyscale clouds on AWS](/clouds/aws/manage.md).
:::

## 3\. Use the Anyscale Terraform module to create an EKS cluster

Anyscale provides a [Terraform module](https://github.com/anyscale/terraform-kubernetes-anyscale-foundation-modules/tree/main/examples/aws/eks-public) to deploy an EKS cluster and supporting AWS resources.

:::note
To use an existing EKS cluster, follow the [existing EKS cluster example](https://github.com/anyscale/terraform-kubernetes-anyscale-foundation-modules/tree/main/examples/aws/eks-existing) or see the [Anyscale Operator documentation](/clouds/kubernetes.md) and the [Anyscale Terraform repository](https://github.com/anyscale/terraform-kubernetes-anyscale-foundation-modules).
:::

Enter information about where you want to deploy your EKS cluster:

Anyscale cloud name `my-eks-cloud`

AWS account ID `1234567890`

AWS region `us-west-2`

EKS cluster name `my-eks-cluster`

Clone the Terraform module and navigate to the EKS example:

```bash
git clone https://github.com/anyscale/terraform-kubernetes-anyscale-foundation-modules
cd terraform-kubernetes-anyscale-foundation-modules/examples/aws/eks-public/
```

Run the following command to create and populate a Terraform variable file:

```bash
cat <<EOF > terraform.tfvars
eks_cluster_name = "<your_eks_cluster_name>"
aws_region = "<your_aws_region>"
EOF
```

:::note
The Terraform example enables GPU node pools (T4) by default. To customize or disable GPU pools, set `gpu_instance_types` in your `terraform.tfvars` (for example, use an empty map `{}` to disable GPU pools).
:::

Run the following commands to apply the Terraform configuration. This may take several minutes.

```bash
terraform init
terraform plan
terraform apply
```

:::note
Some Terraform errors may be resolved by re-running `terraform apply`.
:::

Collect and enter the following values from your Terraform output:

Availability zones `us-west-2a,us-west-2b`

Operator IAM role name `default-eks-node-group`

Storage bucket name `anyscale-1234`

## 4\. Install additional EKS components

In this step, you install the required components for autoscaling, load balancing, and Envoy Gateway on your EKS cluster. For more information about customizing EKS, see the [Anyscale Terraform repository](https://github.com/anyscale/terraform-kubernetes-anyscale-foundation-modules).

Run the following command to connect your terminal to the EKS cluster:

```bash
aws eks update-kubeconfig --region <your_aws_region> --name <your_eks_cluster_name>
```

Install the Kubernetes Autoscaler Helm chart:

```bash
helm repo add autoscaler https://kubernetes.github.io/autoscaler
```

```bash
helm upgrade cluster-autoscaler autoscaler/cluster-autoscaler \
  --version 9.46.0 \
  --namespace kube-system \
  --set awsRegion=<your_aws_region> \
  --set 'autoDiscovery.clusterName'=<your_eks_cluster_name> \
  --install
```

Install the AWS load balancer controller:

```bash
helm repo add eks https://aws.github.io/eks-charts
```

```bash
helm upgrade aws-load-balancer-controller eks/aws-load-balancer-controller \
  --version 1.13.2 \
  --namespace kube-system \
  --set clusterName=<your_eks_cluster_name> \
  --install
```

Install Envoy Gateway v1.7.0:

```bash
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.7.0 \
  --namespace envoy-gateway-system \
  --create-namespace
```

```bash
kubectl wait --for=condition=available deployment/envoy-gateway \
  -n envoy-gateway-system --timeout=120s
```

Create a file named `envoyproxy.yaml` with the following contents:

```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: envoy-proxy
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        annotations:
          service.beta.kubernetes.io/aws-load-balancer-type: external
          service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
          service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
```

Apply the resource:

```bash
kubectl apply -f envoyproxy.yaml
```

Create a file named `gatewayclass.yaml` with the following contents:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: envoy-proxy
    namespace: envoy-gateway-system
```

Apply the resource:

```bash
kubectl apply -f gatewayclass.yaml
```

:::note
Envoy Gateway is the recommended ingress controller for Anyscale on Kubernetes. Other gateway and ingress controllers are supported. See [Ingress and gateway controllers](/clouds/kubernetes.md#ingress-support) for all supported options.
:::

If you intend to use NVIDIA GPUs in your Anyscale workloads, install the NVIDIA device plugin:

```bash
helm repo add nvdp https://nvidia.github.io/k8s-device-plugin
```

```bash
helm upgrade nvdp nvdp/nvidia-device-plugin \
  --namespace nvidia-device-plugin \
  --version 0.17.1 \
  --values sample-values_nvdp.yaml \
  --create-namespace \
  --install
```

## 5\. Register the Anyscale cloud resources

Run the following command with the values from your Terraform output. Verify all variables are entered correctly.

```bash
anyscale cloud register \
  --name <your_cloud_name> \
  --provider aws \
  --region <your_aws_region> \
  --compute-stack k8s \
  --kubernetes-zones us-west-2a,us-west-2b \
  --anyscale-operator-iam-identity arn:aws:iam::<your_aws_account_id>:role/<your_anyscale_operator_iam_role> \
  --s3-bucket-id s3://<your_storage_bucket_name>
```

Record the cloud resource ID from the output in the following field:

Cloud resource ID `cldrsrc_1234`

## 6\. Install and deploy the Anyscale operator on your EKS cluster

In this step, you add the Anyscale operator Helm chart to your EKS cluster, create a `values.yaml` file that describes your cloud and AWS identity, and install the operator with Helm.

### Add the Anyscale operator Helm chart

Run the following command to add the Anyscale operator Helm chart:

```bash
helm repo add anyscale https://anyscale.github.io/helm-charts
helm repo update anyscale
```

### Create the Gateway

The `anyscale-operator` namespace must exist before you create the Gateway. Create it with the following command. If the namespace already exists, this command returns an error; that's expected and you can proceed.

```bash
kubectl create namespace anyscale-operator
```

Create a file named `gateway.yaml`.

Enter your cloud resource ID from step 5. Hyphens are applied automatically for the certificate name:

Cloud resource ID (for certificates) `cldrsrc_1234`

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
  namespace: anyscale-operator
spec:
  gatewayClassName: eg
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    port: 443
    protocol: HTTPS
    hostname: '*.i.anyscaleuserdata.com'
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: anyscale-<cloud-resource-id>-certificate
    allowedRoutes:
      namespaces:
        from: All
  - name: https-session
    port: 443
    protocol: HTTPS
    hostname: '*.s.anyscaleuserdata.com'
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: anyscale-svc-<cloud-resource-id>-certificate
    allowedRoutes:
      namespaces:
        from: All
```

Apply the Gateway and retrieve its external address:

```bash
kubectl apply -f gateway.yaml
```

```bash
kubectl get gateway gateway -n anyscale-operator \
  -o jsonpath='{.status.addresses[0].value}'
```

Record the Gateway address in the following field:

Gateway address `lb.example.com`

### Create a values YAML file

Create a `values.yaml` file. If your load balancer provides a hostname, use `hostname`. If it provides an IP address, use `ip` instead.

```yaml
global:
  cloudDeploymentId: <your_cloud_resource_id>
  cloudProvider: aws
  aws:
    region: <your_aws_region>

workloads:
  serviceAccount:
    name: anyscale-operator

networking:
  gateway:
    enabled: true
    name: "gateway"
    namespace: "anyscale-operator"
    apiVersion: "gateway.networking.k8s.io/v1"
    hostname: "<gateway-address>"
    # ip: "<gateway-ip>"  # Use this instead of hostname if the LB provides an IP address
```

To customize the Helm chart with custom patches or additional pod shapes, see [Configure the Helm chart for the Anyscale operator](/clouds/kubernetes/configure-helm.md).

### Install the Anyscale operator on EKS

Run the following command to install the Anyscale operator with Helm using your `values.yaml` file.

```bash
helm upgrade anyscale-operator anyscale/anyscale-operator \
  --namespace anyscale-operator \
  -f values.yaml \
  --create-namespace \
  --wait \
  -i
```

It may take several minutes for your Anyscale cloud to be ready. You can watch the deployment status with the following command:

```bash
kubectl get deployments anyscale-operator -n anyscale-operator -w
```

## 7\. Verify your Anyscale cloud

Run the following command to verify that your cloud is functional:

```bash
anyscale cloud verify --name <your_cloud_name>
```

---

Previous: [Deploy Anyscale on EKS (cloud setup)](/clouds/aws/setup-eks.md) | Next: [Manage Anyscale on AWS](/clouds/aws/manage.md)