To deploy ArcGIS Enterprise on Kubernetes, you run a bash script along with Kubernetes manifests. The deployment package is available for download from My Esri and is delivered as a .tar.gz file. Prior to running the deployment script, review instructions to get started.
Note:
To run the deployment script in interactive mode, your container registry password must not exceed 30 characters. If your container registry password exceeds 30 characters, you can run the deployment script in silent mode. Before doing so, use the password-encrypt.sh tool to generate an encrypted password, remove any line breaks from it, and specify it in the deploy.properties file as the CONTAINER_REGISTRY_PASSWORD.
Run the deployment script in interactive mode
If you run the ArcGIS Enterprise on Kubernetes deployment script without specifying a configuration parameters file, it opens in interactive mode. The script prompts for each parameter and immediately checks the validity of each value. This provides a fast way to verify each configuration parameter for your deployment.
- On your Kubernetes client machine, open a terminal as an administrator.
- Change directories to where your deployment script is located.
- Create the encryption keyfile.
The encryption keyfile is a plain text file used for AES-256 encryption and decryption of passwords. The content of this file is plain text that you specify and should not contain passwords. This file should remain in a fixed location and the contents should not be changed.
- (Optional) Create the TLS secret in the namespace.
- In the terminal, run the deployment script using the following command format:
./deploy.sh - Complete the parameters.
The script prompts you for the following parameters, one at a time. If you provide an invalid value, the script immediately returns an error and prompts for a valid parameter. The following is a summary of the user inputs:
Note:
You do not need to run this script as the root user.
- Deployment platform—ArcGIS Enterprise on Kubernetes uses ingress to route incoming traffic to the services in the cluster. If you are deploying in a managed Kubernetes service by a cloud provider, such as Amazon Web Services EKS or Microsoft Azure Kubernetes Service (AKS), the ingress controller can be exposed externally using a load balancer service by the cloud provider. In this case, ArcGIS Enterprise on Kubernetes provisions a load balancer during the deployment process.
- Load balancer—During deployment, ArcGIS Enterprise on Kubernetes can provision selected cloud load balancers with the Azure Load Balancer (external and internal) and AWS Network Load Balancer (NLB-External and NLB-Internal). Each option prompts you to specify the load balancer's IP. In this release, only the Azure load balancers support this option; AWS EKS does not support the load balancer IP option. To use layer 7 load balancing capabilities through a preexisting ingress controller, you must indicate that you don't want to use a cloud load balancer.
- Cluster-level ingress controller—A cluster-level ingress controller can be used to route traffic to an ArcGIS Enterprise on Kubernetes deployment, allowing for organizations to use layer 7 load balancing capabilities. To allow for the creation of the in-cluster NGINX ingress controller service as type ClusterIP, answer yes when asked about using a cluster-level ingress controller.
- Namespace—The Kubernetes cluster namespace where ArcGIS Enterprise on Kubernetes will be deployed.
- Encryption Keyfile—The encryption keyfile that you created in step 3.
- Registry Host—The fully qualified domain name (FQDN) of the container registry host (for example, docker.io).
- Image Path—The image repository that's used to pull the container images (for example, esridocker).
- Registry Username—The username for an account in the specified container registry that stores permissions to pull from the registry.
Caution:
The container registry account that you specify should have a minimum level of privileges associated with it, for example, only those to download container images. By default, Kubernetes stores and accesses this account's unencrypted credentials as a secret. It is recommended that you do not specify an account that has privileges to push changes, edit metadata, or administer the container registry.
- Registry Password—The password for the specified container registry account.
- Fully Qualified Domain Name—The FQDN needed to access ArcGIS Enterprise on Kubernetes. This points to a load balancer, reverse proxy, edge router, or other web front-end point configured to route traffic to the ingress controller.
- Context Path—The context path used
in the URL for ArcGIS Enterprise on Kubernetes (for
example,
https://<FQDN>/<context
path>).
Note:
Once deployment is complete, the context path you specify here will be used when configuring ArcGIS Enterprise on Kubernetes Web Adaptor with your organization.
- Node Port—The ingress controller exposes external traffic over service type "LoadBalancer" or "NodePort". The port can be specified in the range of 30000-32767. If a port is not specified, Kubernetes automatically allocates an available port in this range.
- TLS Certificate—A TLS certificate (either self-signed or third-party CA-signed) is required with the FQDN and subject alternate name. This will be the default TLS certificate for the ingress controller.
- Answer the prompt asking whether you want to deploy or save the properties file.
If you need to customize any parameters in the properties file including the additional silent deployment properties, the deployment script should be exited and the file on disk updated. Common examples of additional properties include updating the ALLOWED_PRIVILEGED_CONTAINERS=false to run only unprivileged containers or updating the K8S_AVAILABILITY_TOPOLOGY_KEY=topology.kubernetes.io/zone to support a multi-availability zone cluster deployment.
When you have provided all valid parameters, a properties file is saved to your current working directory. Use this property file to automate future deployments or undeploy ArcGIS Enterprise on Kubernetes.
The final deployment step is to create your ArcGIS Enterprise organization.
Tip:
The deployment script uses kubectl commands to validate prerequisites, such as a valid namespace. If the kubectl command is unable to communicate with the cluster due to a network or firewall issue, the deployment script may appear to become unresponsive. If this happens, end the ./deploy.sh command and run kubectl directly from a terminal to initiate communication with the cluster.
Run the deployment script in silent mode
As an alternative to running the deployment script in interactive mode, you can deploy ArcGIS Enterprise on Kubernetes silently. The deployment script is bundled with a deploy.properties file, which provides a set of parameters prompting for unique input to your ArcGIS Enterprise on Kubernetes deployment.
- On your Kubernetes client machine, open a terminal as an administrator.
- Change directories to where your deployment script and the deploy.properties file are located.
- Open the deploy.properties file.
- Refer to the descriptive comments in the file for a summary of the user inputs and provide values for each parameter listed in the file.
The file is divided into the following sections:
- Deployment platform
- Namespace
- Encryption keyfile
- Container registry
- Fully Qualified Domain Name (FQDN)
- TLS certificate
- Additional properties
- Save the file. Optionally, rename the file.
- In the terminal, run the password-encrypt.sh tool to generate encrypted passwords for use in the deploy.properties file.
- In the terminal, run the deployment script using the following command format:
./deploy.sh -f <user_properties>
The contents of <user properties> are derived from the deploy.properties file.
Before deploying ArcGIS Enterprise on Kubernetes, the deployment script will validate whether your system meets the minimum system requirements and whether you have provided valid input for each parameter listed in the deploy.properties file.
The final deployment step is to create your ArcGIS Enterprise organization.
Additional silent deployment properties
The deploy.properties file contains additional properties that can be used when deploying silently. The default values for each are provided.
ALLOWED_PRIVILEGED_CONTAINERS=true—If you cannot run a privileged container, set this value to false. When doing so, you'll also need to run the # "sysctl -w vm.max_map_count=262144" command as root to increase vm.max_map_count to 262144 on all nodes in your cluster.
CONTAINER_IMAGE_PULL_POLICY="Always"—When new containers are started, the ImagePullPolicy determines whether a new container image is pulled from the container registry. The default is "Always" and will pull a new image each time a container is started. If you want a new image to be pulled only if one is not already present, set this value to "IfNotPresent".
INGRESS_HSTS_ENABLED=false—HTTP Strict Transport Security (HSTS) adds a layer of security to your organization's web traffic. By default, the HSTS protocol option is set to false. To turn on HSTS, set this value to true.
INGRESS_SSL_PROTOCOLS="TLSv1.2 TLSv1.3"—Sets the SSL protocols to use. The default is "TLSv1.2 TLSv1.3". If additional TLS versions must be allowed, specify them here.
INGRESS_SSL_CIPHERS="ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-CHACHA20-POLY1305:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA"—This property sets the list of SSL ciphers to enable. If additional SSL ciphers are required, specify them here.
K8S_CLUSTER_DOMAIN="cluster.local"—If you have a custom cluster domain suffix for services and pods (for example, organization.com), you can use this property to allow ArcGIS Enterprise on Kubernetes to use your cluster domain suffix. The default value is cluster.local.
K8S_AVAILABILITY_TOPOLOGY_KEY="kubernetes.io/hostname"—If you are deploying ArcGIS Enterprise on Kubernetes and your Kubernetes cluster spans three or more availability zones, replace "kubernetes.io/hostname" with "topology.kubernetes.io/zone" or your custom domain topology label. For more information about multi-availability zone deployments, see Multi-availability zone Kubernetes cluster administration.
INGRESS_SERVICE_USE_CLUSTER_IP=false—To use layer 7 load balancing capabilities through a preexisting ingress controller, you must set this value to true. Setting this value to true will override the value that has been set for the INGRESS_TYPE parameter.
Note:
Custom annotations can be added to the NGINX ingress controller service when running the deployment script silently. These annotations could be applied if, for example, you wanted to customize the attributes of a layer 4 cloud load balancer during deployment. Examples of how these annotations can be added can be found in the deploy.properties.template file.
CLUSTER_INGRESS_CONTROLLER_YAML_FILENAME="ingress.yaml"—If you set INGRESS_SERVICE_USE_CLUSTER_IP to true and haven't already created the Ingress object, you can create the Ingress object by setting this value to the full path of the Ingress YAML file. This option is only available for supported layer 7 load balancers. This value is blank by default and the property will be ignored unless you specify the path.
After updating the necessary parameters for your organization's cluster in the deployment properties file, deploy ArcGIS Enterprise on Kubernetes using the following command:
./deploy.sh -f <user_properties>