Deploy a cluster in Amazon Elastic Kubernetes Service

Before deploying ArcGIS Enterprise on Kubernetes in Amazon Web Services (AWS), you must prepare an Amazon Elastic Kubernetes Service (EKS) cluster that meets ArcGIS Enterprise system requirements.

Preparing an EKS cluster includes steps that are common across supported environments such as setting up the Kubernetes cluster and corresponding nodes, and steps that are environment specific such as configuring AWS Identity and Access Management (IAM) roles.

Carefully review the following steps and navigate to AWS documentation for more detailed instructions on how to prepare your environment.

  1. Create an Amazon Virtual Private Cloud (VPC).

    You must create a VPC that meets both the Amazon EKS requirements and the scalability requirements of ArcGIS Enterprise on Kubernetes.

    A large Kubernetes deployment can consume thousands of IP addresses. Once a cluster is created, the Classless Inter-Domain Routing (CIDR) ranges of the VPC and associated subnets cannot be modified.

    The number of IP addresses you need will largely depend on the number of workloads within the cluster, but scalability testing has shown that each subnet should be configured with a minimum subnet mask of /18. This allows for more than 16,000 available IP addresses per subnet.

  2. Optionally, enable envelope encryption of secrets and create a Key Management Service (KMS) key.

    It is recommended that you enable envelope encryption for the secrets stored in ectd for the EKS cluster. To do so, a symmetric encryption key must be present in Amazon EKS.


    Once envelope encryption has been enabled for a cluster, it cannot be disabled. It can be enabled on an existing cluster if needed.

  3. Create an EKS cluster.

    When creating an EKS cluster, you will reference the VPC, subnets, IAM role, and KMS key created in the previous steps. ArcGIS Enterprise on Kubernetes is not supported on AWS Fargate, as the underlying nodes are not configurable.

    The cluster Kubernetes version should match what is listed in the System requirements.

  4. Create a node group IAM role.

    Once a cluster is created, you must create a worker node group. Creating a node group requires an additional IAM role that defines the AWS services that the associated EC2 instances are able to access.

  5. Create a node group.

    Once created, a cluster does not have any schedulable worker nodes. To deploy any workloads to the cluster, at least one node group is required to spin up the associated pods. Using a managed node group is recommended to allow for streamlined upgrades of the cluster in the future.

  6. Update the kubectl configuration.

    After creating the cluster, the AWS Command Line Interface (CLI) can be used to pull the cluster-admin connection information into your kubeconfig file. Use the following command:

    aws eks update-kubeconfig -name <CLUSTER_NAME> --region <REGION>
  7. Create a cluster IAM role.

    An Amazon EKS cluster requires an IAM role that defines what resources the cluster has access to. ArcGIS Enterprise on Kubernetes does not have any requirements beyond what AWS outlines.

  8. Create an OpenID Connect (OIDC) identity provider.

    To interface with other AWS services from within the cluster, an OIDC provider is recommended by AWS. This provider federates the Kubernetes cluster with the AWS organization to map Kubernetes services accounts access to AWS resources. In terms of ArcGIS Enterprise on Kubernetes, this is recommended to allow the operation of the AWS Load Balancer Controller and the Amazon Elastic Block Store (EBS) Container Storage Interface (CSI) Driver. Those two add-ons greatly reduce the administrative effort required to deploy ArcGIS Enterprise on Kubernetes.

  9. Install the Load Balancer Controller add-on.

    The AWS Load Balancer Controller enables the provisioning of a Network Load Balancer (internal or external) during the deployment process. The controller also accounts for the creation of the target group, security groups, and other settings to manage routing from the Network Load Balancer to the worker nodes.

    If the load balancer is manually created, these settings must be configured manually. The first step is to create the IAM role and a Kubernetes service account. The second step is to deploy the AWS Load Balancer Controller workloads to the cluster.

  10. Install the Amazon EBS CSI Driver add-on.

    The Amazon EBS CSI Driver is a requirement from Amazon EKS 1.23 and later that allows for dynamic provisioning of EBS volumes via Persistent Volumes Claims (PVCs) within the cluster. The first major step is to create an IAM role and a Kubernetes service account for the CSI driver. The second is to deploy the CSI driver workloads to the cluster.

    To take advantage of the latest class of EBS volumes, it is recommended that you create a storage class referencing the gp3 type. The appropriate YAML file should be applied to the cluster using the following command:

    kubectl apply -f <storageClass.yaml>

    See a sample default storage class YAML and a sample backup storage class YAML for more information.

Once you have created a namespace in your Kubernetes cluster, your EKS cluster should be ready for you to deploy and configure ArcGIS Enterprise. When you deploy, remember to tell ArcGIS Enterprise to create the load balancer. When you configure your organization, be sure to reference the storage class you created.