The templates provide GitHub Actions workflows for ArcGIS Enterprise operations on Amazon Web Services (AWS) for Windows, Linux, and Kubernetes platforms.
The workflows require:
- GitHub.com user account or GitHub Enterprise Server with enabled GitHub Actions
- Amazon Web Services (AWS) account
- (For Windows and Linux platforms) ArcGIS Online user account to download ArcGIS Enterprise installation media from MyEsri
- (For Kubernetes platform) Docker Hub account that has access to private repositories with ArcGIS Enterprise on Kubernetes container images
- Authorization files for ArcGIS Enterprise software
- SSL certificates for the ArcGIS Enterprise site domain names
On Windows and Linux platforms the workflows use:
- AWS CLI to manage AWS resources
- Packer by HashiCorp to build ArcGIS Enterprise EC2 AMIs
- Terraform CLI by HashiCorp to provision infrastructure in AWS
- AWS Systems Manager (SSM) to remotely manage system and application configuration of the EC2 instances
- Python scripts to invoke AWS services and download installation media
- Cinc Client and Chef Cookbooks for ArcGIS to install and configure ArcGIS Enterprise applications, or
- Ansible and Ansible Collections for ArcGIS to install and configure ArcGIS Enterprise applications
- Enterprise Admin CLI container image to test the deployment
On Kubernetes platform the workflows use:
- AWS CLI to manage AWS resources
- Terraform CLI by HashiCorp to provision infrastructure in AWS
- Helm Charts for ArcGIS Enterprise on Kubernetes to install and configure ArcGIS Enterprise organization
- Enterprise Admin CLI container image to invoke ArcGIS Enterprise Admin services and test the deployment
Basic knowledge of Git and AWS is required to use the templates. Knowledge of the other technologies is recommended to modify or extend the templates.
An ArcGIS Enterprise site in this context is a group of deployments that typically include a base ArcGIS Enterprise deployment or ArcGIS Enterprise on Kubernetes deployment plus additional server deployments in different roles.
The following templates are available for AWS:
- arcgis-site-core - Provision core AWS resources for ArcGIS Enterprise site
- arcgis-enterprise-base-windows - Base ArcGIS Enterprise on Windows deployment operations
- arcgis-enterprise-base-linux - Base ArcGIS Enterprise on Linux deployment operations
- arcgis-enterprise-k8s - ArcGIS Enterprise on Kubernetes deployment operations
- arcgis-server-linux - ArcGIS Server on Linux deployment operations
By default, the workflows are configured with "workflow_dispatch" event that enables workflows to be triggered manually. To trigger a workflow manually, navigate to the repository on GitHub, click on the "Actions" tab, select the workflow to run, select the branch, and click the "Run workflow" button.
Note that the deployments may belong to different environments such as "production" and "staging". Each environment may have its own branch in the repository. The list of workflows in GitHub Actions page shows only the workflows present in /.github/workflows directory of the "main" branch, but the workflow runs use the workflow files from the selected branch. To enable workflows, copy the workflows' .yaml files from the template's
workflowsdirectory to/.github/workflowsdirectory in both themainbranch and the environment branch, commit the changes, and push the branches to GitHub.
The workflows can be modified to use other triggering events such as push, pull_request, or schedule. Consider using "schedule" event to schedule backups and "pull_request" event to check the infrastructure changes by "terraform plan" command.
The workflows use configuration files to define the parameters of the deployments. The configuration files are in JSON format and are stored in the /config/aws directory of the repository. The configuration files must be in the same branch as the workflows that use them.
The configuration files may reference other files such as software authorization files and SSL certificates. The workflows symlink ~/config/ paths to the config directory path in the GitHub Actions runner workspace. Keep the referenced files in subdirectories of the /config directory and reference them as ~/config/<dir>/<file>.
AWS permissions required by the workflows are defined in IAM policies JSON files. Modify the JSON files if needed and use them to create IAM policies.
A Terraform module can call other modules to include their resources into the configuration. A module that has been called by another module is often referred to as a child module. The templates use a collection of child modules that can be called multiple times within the same configuration, and multiple configurations can use the same child module.
The specific guidance for using the templates depends on the use case and may involve various customizations. The following steps just demonstrate the typical use case.
Create a new private GitHub repository from https://github.com/esri/arcgis-gitops template repository.
Use separate GitHub repositories for each ArcGIS Enterprise site and separate Git branches for different environments.
When operating multiple similar ArcGIS Enterprise sites, consider first forking and modifying https://github.com/esri/arcgis-gitops template repository and then creating repositories for the sites from the modified template.
Create IAM user that will be used by the workflows and add the required policies to the user.
The templates use the same AWS credentials for all the workflows. To implement the principle of least privilege and enforce separation of duties with appropriate authorization for each interaction with AWS resources, consider modifying the workflows to use different AWS credentials for different workflows. Consider using separate IAM users for core infrastructure, deployments infrastructure, and application workflows.
Create a private S3 bucket for the Terraform backend. Make sure that the IAM user has the S3 bucket permissions required by Terraform.
It is recommended that to enable bucket versioning on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.
Configure secrets and variables for GitHub Actions in the repository settings.
| Name | Description |
|---|---|
| AWS_ACCESS_KEY_ID | AWS access key Id |
| AWS_SECRET_ACCESS_KEY | AWS secret access key |
For ArcGIS Enterprise on Windows and Linux:
| Name | Description |
|---|---|
| ARCGIS_ONLINE_USERNAME | ArcGIS Online user name |
| ARCGIS_ONLINE_PASSWORD | ArcGIS Online user password |
For ArcGIS Enterprise on Kubernetes:
| Name | Description |
|---|---|
| CONTAINER_REGISTRY_USER | Docker Hub user name |
| CONTAINER_REGISTRY_PASSWORD | Docker Hub user password |
| Name | Description |
|---|---|
| AWS_DEFAULT_REGION | Default AWS region Id |
| TERRAFORM_BACKEND_S3_BUCKET | Terraform backend S3 bucket |
Run validate-settings-aws GitHub Actions workflow to validate the settings.
If the GitHub subscription plan supports GitHub Actions Environments, consider environment secrets to use secrets specific to each environment.
Follow the arcgis-site-core template instructions to provision core AWS resources for the ArcGIS Enterprise site.
Consult the README files of the other templates to create and operate the required ArcGIS Enterprise deployments.