The Esri arcgis-enterprise-ha.template.json Amazon Web Services (AWS) CloudFormation template provisions a highly available base ArcGIS Enterprise deployment on two Amazon Elastic Compute Cloud (EC2) instances plus one EC2 instance for a file server.
The template installs and configures the following products on two identical EC2 instances and configures each component so that data and services are available even if one machine in the deployment fails:
- Portal for ArcGIS
- ArcGIS Server
- ArcGIS Web Adaptor
- ArcGIS Data Store
In addition, you can do either of the following for the GIS Server configuration store and Portal for ArcGIS content directory:
- Place the Portal for ArcGIS content directory in an Amazon Simple Storage Service (S3) bucket, ArcGIS Server configuration store in a combination of Amazon DynamoDB and Amazon S3, and ArcGIS Server shared directories on a separate file server EC2 instance.
- Place the Portal for ArcGIS content directory, ArcGIS Server configuration store, and shared server directories on a file server EC2 instance.
Note:
If you store your ArcGIS Server configuration store in Amazon DynamoDB and S3 and your Portal for ArcGIS content directory in an S3 bucket, they are deleted when you delete this deployment. If you want to keep this content, make a copy of it before deleting the deployment.
This template creates the following architecture in Amazon Web Services:
You must create the Amazon Virtual Private Cloud (VPC), subnets, and load balancer before running this template.
License:
Certain icons in the diagram are used with permission from Amazon Web Services.
Prerequisites
Prerequisites can be grouped by the items—such as files and accounts—that you must obtain and the tasks you must perform before running the CloudFormation template.
Required items
You need the following before running this template:
- An Amazon Web Services account.
The account must have access to basic AWS services such as CloudFormation, Amazon Elastic Compute Cloud (EC2), Amazon Virtual Private Cloud (VPC), Amazon Simple Storage Service (S3), Systems Manager, Amazon CloudWatch, Lambda, AWS Identity and Access Management (IAM), Amazon DynamoDB, Secrets Manager, AWS Certificate Manager, and Amazon Relational Database Service (RDS).
- Esri licenses. License files for Portal for ArcGIS, ArcGIS GIS Server, and any ArcGIS Server licensing roles you have in addition to the base deployment. All license files must be for the same ArcGIS version.
- An SSL certificate file or certificates (in .pfx format) and corresponding passwords. Certificates must be from a certifying authority.
- An Amazon Virtual Private Cloud (VPC) and subnets.
You can use one of the following CloudFormation templates to create a VPC: VPC with two public subnets or VPC with two public and private subnets with a NAT Gateway.
- If you create a deployment on Ubuntu EC2 instances in AWS GovCloud, you need an AMI ID. If you want to use the base canonical Ubuntu AMI, follow the instructions in Esri Amazon Web Services CloudFormation templates to identify the ID.
- The arcgis-enterprise-ha.template.json CloudFormation template.
Required tasks
Complete the following tasks before running this template:
- Prepare a deployment Amazon Simple Storage Service (S3) bucket in your AWS account. You will specify the bucket name in the template when you launch the stack.
- Create a bucket or use an existing S3 bucket. You must be the owner of the bucket.
- Upload your ArcGIS software authorization files to the bucket.
- Upload your SSL certificate file to the deployment bucket.
- Create a fully qualified domain name for your deployment. This domain name must be resolvable. Ask your IT administrator if you are unsure how to create and configure a domain name.
- Configure passwords in AWS Secrets Manager (optional but recommended).
You can configure the passwords for accounts such as the site administrator username and the Windows arcgis user password in AWS Secrets Manager. This provides you with a secret Amazon Resource Name (ARN). Use the ARN in place of a password in the template parameters when you launch a stack. If you don't use AWS Secrets Manager for storing passwords, you must type passwords in plain text in the template parameter when launching the stack.
Note:
When creating a secret ARN in AWS Secrets Manager for a password to be used with Esri CloudFormation templates, you must use the Other types of secrets secret type and use the Plaintext option. For more information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS.
Tip:
By default, CloudFormation deletes partially created resources if stack creation fails. This is helpful because it removes unusable deployments from your account, but it can make it difficult to troubleshoot. To retain the stack in its failed state, disable the Rollback on failure CloudFormation stack creation option before launching the stack. See Setting AWS CloudFormation options in the AWS help for more information.
Parameters
Refer to the following tables for descriptions of the parameters used in this CloudFormation template. Tables are grouped by parameter type.
Amazon EC2 Configuration
| Parameter name | Required? | Parameter description |
|---|---|---|
Platform Type | Required | Choose the operating system platform. Supported types are as follows:
For specific operating system versions, see Operating systems supported when using CloudFormation to ArcGIS deploy on AWS. |
EC2 Instance AMI ID | Optional | You can leave this parameter value empty. If you do, CloudFormation templates will use the latest Amazon Machine Image (AMI) ID for Microsoft Windows Server 2019 or Ubuntu Server 20.04 LTS based on the type of platform you selected. Note:Prior to January 2024, the default Ubuntu Server version was 18.04. You cannot leave this parameter empty if you deploy in AWS GovCloud on a Linux platform. See Esri Amazon Web Services CloudFormation templates for instructions on finding the ID for the base Ubuntu AMI from Canonical. If you deploy on a supported Linux operating system other than Ubuntu, you can find the AMI ID using AWS Management Console or in AWS Marketplace. The first time you use one of the default AMIs for a specific release, you must accept AWS Marketplace terms. If you want to use your own custom AMI, you can type the AMI ID using one of the following:
If you use a custom AMI, ensure that it meets the following requirements:
|
EC2 Instance Keypair Name | Required | Choose an EC2 keypair name to allow remote access to EC2 instances. |
Amazon VPC Configuration
| Parameter name | Required? | Parameter description |
|---|---|---|
VPC ID | Required | Choose a VPC ID. Note:All ArcGIS Enterprise components that are part of the same deployment must be deployed in the same VPC. If you need to create a VPC, you can use one of the VPC sample templates: VPC with public subnets or VPC with public and private subnets and a NAT Gateway. |
Subnet ID 1 | Required | Choose a subnet ID. The subnet ID that you select must be within the VPC you have selected above. If you used an Esri CloudFormation template to create the VPC, you can get the subnet ID from that template's output parameters. |
Subnet ID 2 | Required | Choose a second subnet ID. This must be a different subnet ID than you used for the Subnet ID 1 parameter. The subnet ID that you select must be within the VPC you specified for this deployment. If you used an Esri CloudFormation template to create the VPC, you can get the subnet ID from that template's output parameters. |
Domain Name System (DNS) Configuration
| Parameter name | Required? | Parameter description |
|---|---|---|
ArcGIS Enterprise Deployment Domain Name | Required | Provide the fully qualified domain name for the ArcGIS Enterprise deployment. The domain name must exist and be resolvable. Contact your IT administrator if you are not sure of the domain name to use. |
Elastic Load Balancer DNS Name | Required | To use an elastic load balancer (ELB) with the deployment, provide the value for an application or classic ELB DNS name. This ELB must already exist. You can get the ELB DNS name by browsing to the Load Balancers section of the Amazon EC2 service within the AWS Management Console or, if you used an Esri CloudFormation template to create the ELB, you can get it from that template's output parameters. Valid ELB DNS names must end with .elb.amazonaws.com. |
ArcGIS Enterprise Configuration
| Parameter name | Required? | Parameter description |
|---|---|---|
EC2 Instance Type | Required | Specify an EC2 instance type. The default is m5.2xlarge. This is the instance type that will be used for the ArcGIS Enterprise machine. This EC2 instance will be configured with the AWS Auto Recovery feature. If the instance fails, AWS can restore it in the same Availability Zone to the stage before it failed. |
EC2 Instance Root Drive Disk Space | Required | This is the size of the root drive disk space for the ArcGIS Enterprise EC2 instance. Provide the size of the root drive in GB. The default is 100 GB. Minimum is 100 GB. Maximum is 1024 GB. |
Deployment Bucket Name | Required | Provide the name of the Amazon S3 bucket that contains your software license files and SSL certificates. This bucket must already exist and contain the license file and SSL certificate for your deployment. You must be the owner of the bucket and it must reside in the same AWS account as your deployment. |
Portal License File Name | Required | Provide the Portal for ArcGIS authorization file object key name. You must upload the license file (.json file) to the deployment bucket before launching this stack. You can get the file object key name by browsing to the file in the deployment bucket in the AWS S3 console, for example, portal.json or resources/licenses/portal/portal.json. License file names are case sensitive. Ensure that you type the correct name and case. |
User License Type ID | Optional | Provide a portal user license type ID. For information on user types, see User types, roles, and privileges. If you are not sure what type to use, leave this field empty. In this case, a temporary user license type ID is used. Note:If you do not provide a user license type ID now, you must change the user license type after creating the deployment. |
Server License File Name | Required | Provide the ArcGIS Server authorization file object key name. You must upload the license file (.ecp or .prvc) to the deployment bucket before launching this stack. To get the file object key name, browse to the file in the deployment bucket in the Amazon S3 console, for example, server.prvc or resources/licenses/server/server.prvc. You must use an ArcGIS GIS Server license because it will be used to license the hosting server. License file names are case sensitive. Ensure that you type the name correctly. |
Portal and Server Administrator User Name | Required | Provide a user name for the initial portal administrator and the ArcGIS Server primary site administrator. |
Portal and Server Administrator User Password | Required | Provide a password for the initial portal administrator and the ArcGIS Server primary site administrator. You can either type a plain text password or the ARN of your secret ID from AWS Secrets Manager. The password must be 8 or more alphanumeric characters and can also contain dots (.). The password cannot contain any other special characters or spaces. For more information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS. It's a best practice to manage your passwords in AWS Secrets Manager. For information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS. |
Windows arcgis user password | Conditional | Provide a password for the arcgis user. The arcgis user is a local Windows login used to run the ArcGIS software services; therefore, this password is only required if you deploy on Windows. You can either enter a plain text password or the ARN of your secret ID from AWS Secrets Manager. It's a best practice to manage your passwords in AWS Secrets Manager. For information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS. |
Configuration Store Type | Required | Choose where the ArcGIS Server configuration store will be located. The default is FileSystem.
Note:Even if you choose CloudStore, a separate file server is created to host the ArcGIS Server shared directories.See the Considerations section below for information about DynamoDB capacity. |
ArcGIS File Server Instance Type | Required | Choose an EC2 instance type for the ArcGIS file server. The default instance type is m5.2xlarge. |
ArcGIS File Server EC2 Instance Root Drive Disk Space | Required | The size of the root drive disk space for the ArcGIS file server EC2 instance. Provide the size of the root drive in GB. The default is 100 GB. Minimum is 100 GB. Maximum is 1024 GB. |
Portal Web Adaptor Name | Required | Provide the web adaptor name for the portal. Access to the portal is through a URL in the format https://<fully qualified domain name>/<web adaptor name>. The name must begin with a letter and contain only alphanumeric characters. |
Server Web Adaptor Name | Required | Provide the web adaptor name for the ArcGIS Server site. Access to the ArcGIS Server site is through a URL in the format https://<fully qualified domain name>/<web adaptor name>. The name must begin with a letter and contain only alphanumeric characters. |
SSL Certificate File Name | Required | Provide an SSL certificate from a certifying authority (.pfx file). You must upload the certificate to the deployment bucket before launching this stack. You can get the file object key name by browsing to the file within the deployment bucket in the AWS S3 console, for example, domainname.pfx or resources/sslcerts/domainname.pfx. |
SSL Certificate Password | Required | Provide the password for the SSL certificate. You can either type a plain text password or the ARN of your secret ID from AWS Secrets Manager. For information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS. |
Outputs
When your stack is created successfully, you can see the following output parameters on the Outputs tab of the CloudFormation stack in AWS Management Console.
| Output name | Output description |
|---|---|
DeploymentLogsURL | This is the URL for the Amazon CloudWatch logs where all deployment logs are stored. You can refer to these logs for troubleshooting purposes if your deployment fails. |
PortalHomeAppURL | The URL to access the portal. |
ServerManagerDirURL | The ArcGIS Server Manager URL. |
ServerRestDirURL | The ArcGIS Server REST Services URL. |
StopStackFunctionName | This is the Stop Stack Lambda function URL. You can use this lambda function to stop all EC2 instances in the stack. |
StartStackFunctionName | This is the Start Stack Lambda function URL. You can use this lambda function to start all EC2 instances in the stack that you previously stopped. |
Considerations
The following are important points to consider after creating a CloudFormation stack containing ArcGIS deployments:
- If you choose CloudStore for the Configuration Store Type parameter, the Amazon DynamoDB provision capacity units are set to the following:
- Read capacity units: 250 tables
- Write capacity units: 25 tables
The estimated cost for these settings is approximately $36 per month. Esri testing indicates these settings work well for publishing approximately 500 services. You can edit this setting in the AWS Management Console to decrease the units and lower the cost or increase the units to accommodate more services. Keep in mind that some functionality, such as publishing, will fail if you don't have enough capacity.
- Do not delete any AWS resource created by this CloudFormation template. If you want to know what AWS resources have been created by this template, refer to the Resources tab of this stack in the AWS Management Console. Each resource created by an Esri CloudFormation template also has metadata tags. However, some of the resources do not show tags in the AWS Management Console.
- You can use the AWS Lambda functions that appear in your stack outputs (listed in the Outputs section of this page) to stop EC2 instances in this stack when they are not in use and start them again when required. These functions are useful to help you manage costs.
When you run the Lambda function to stop the EC2 instances in the deployment, the function returns a message that the instances are stopped. However, if the instances participate in an Auto Scaling group, the function must also detach the instances from the group. This can take up to 10 minutes to complete. Therefore, wait at least 10 minutes before you run the Lambda start function to restart the deployment.
- If you use AWS Secrets Manager for passwords, such as the site administrator user password or the Windows arcgis user password, and later (after you create the deployment) you change those passwords, be sure you update the appropriate AWS Secrets Manager ARN's with the updated passwords.
- If you use an Application Load Balancer in your deployment, you can adjust the Application Load Balancer idle timeout after you create the deployment. For example, you may need to increase the idle timeout to ensure that operations that take a long time to complete on any of the machines in the deployment. Adjust the Application Load Balancer idle timeout value in AWS Management Console.
Troubleshooting
If you observe any failures when creating this CloudFormation stack, see Troubleshoot ArcGIS deployments on AWS.