This project uses the AWS Cloud Development Kit, AWS Systems Manager, and ArcGIS PowerShell DSC Libraries to automate the deployment of AWS Infrastructure and ArcGIS Enterprise.
- An AWS Account
- Access to ArcGIS Installation and License files
- AWS Command Line Interface (CLI)
- AWS Cloud Development Kit
- Ability to create DNS Records to Point to A Record
- Amazon Certificate Manage Certificate
The AWS Cloud Development Kit is a relatively newer tool that allows developers to create code in the language that they are most comfortable in and translate that into AWS Infrastructure by generating CloudFormation templates.
Before proceeding, ensure you have both the AWS CLI
and AWS CDK
available and working (see prerequisites for more information)
The cdk.json
file tells the CDK Toolkit how to execute your app.
This project is set up like a standard Python project. The initialization
process also creates a virtualenv within this project, stored under the .env
directory. To create the virtualenv it assumes that there is a python3
(or python
for Windows) executable in your path with access to the venv
package. If for any reason the automatic creation of the virtualenv fails,
you can create the virtualenv manually.
To manually create a virtualenv on MacOS and Linux:
$ python -m venv .env
After the init process completes and the virtualenv is created, you can use the following step to activate your virtualenv.
$ source .env/bin/activate
If you are a Windows platform, you would activate the virtualenv like this:
% .env\Scripts\activate.bat
Once the virtualenv is activated, you can install the required dependencies.
$ pip install -r requirements.txt
At this point you can now synthesize the CloudFormation template for this code.
$ cdk synth
To add additional dependencies, for example other CDK libraries, just add
them to your setup.py
file and rerun the pip install -r requirements.txt
command.
cdk ls
list all stacks in the appcdk synth
emits the synthesized CloudFormation templatecdk deploy
deploy this stack to your default AWS account/regioncdk diff
compare deployed stack with current statecdk docs
open CDK documentation
Now that you have your virtual environment setup with AWS CDK, let's take a look at how this repo is using it. There is an arcgis_cdk_config.json file in the arcgis_cdk directory. The following parameters can be used.
stack_name
- the name of your stack (example - "maps")high_availability
- true/falsecert_arn
- ARN for your ACM certificatefile_server_size
- EC2 Instance Class and Type (example - "m5.2xlarge")kp_name
- key pair namepublic_hosted_zone_id
- zone id for your Route53 public hosted zone
Once the arcgis_cdk_config.json has been updated, run the following commands to deploy your code.
$ cdk synth
Note: you can find the resulting CloudFormation template that was created in the cdk.out directory
$ cdk deploy
Take a look in your AWS Account and notice everything that was deployed
The CDK deploys the following resource to your AWS account:
- A new VPC with multiple public/private subnets
- EC2 Instances in the private Subnet
- ALB in the public Subnet with a listener on 443
- Path based routing rules for the listener
- ACM Certificate attached to the listener
- Route53 Record Set for an existing Public Hosted Zone that maps to the ALB
- A new Route53 private hosted zones with record sets mapping to each EC2 Instance
A logical diagram of the infrastructure can be found below:
Run Commands from AWS System Manager will be used to remotely execute code on the EC2 Instances. This will be done in two steps. We must first prep the instances with our software, then execute the PowerShell DSC scripts.
Now that we have our infrastructure, we need to populate our PowerShell DSC file. There is a sample file title DSCConfigurations-Sample.json
in the repo.
A detailed review of the Variables can be found at the Variable Reference page:
You will need to edit this file we your private IP addresses from the arcgis_cdk deployment above.
We are going to execute code remotely on EC2 Instances and some of the execution requires files to be present in our S3 bucket that was created by the CDK.
The following things need to be upload into the S3 bucket:
- ArcGIS Software Install files (Portal for ArcGIS, ArcGIS Server, ArcGIS Datastore, and Web Adaptor for IIS)
- ArcGIS Licenses files (Portal & Server)
- The PowerShell DSC Configuration File that was edited above
Before we get started with installing PowerShell DSC via the Invoke-ArcGIS Command we need to do a little machine prep. The prep includes:
- Downloading the software and licenses from the S3 bucket created by the arcgis_cdk run
- Portal for ArcGIS (and license)
- ArcGIS Server (and license)
- ArcGIS DataStore
- ArcGIS Web Adaptor for Microsoft IIS
- Downloading the PowerShell DSC modules and adding the ArcGIS Modules to PowerShell
- Adding a local account to each machine for Windows Remote Management (WInRM)
- Changing the execution policy
- Enabling Windows Remote Management (WinRM) to that one machine can execute the commands
Edit the following sections within the EC2InstancePrep.ps1
file:
- Bucket name & Object Keys
- License file name
- IP Addresses of machines
- Username / Password of service account
Login to your AWS Account to Execute the Code:
- Ensure the ArcGIS Enterprise Software has been uploaded to the S3 bucket created by the CDK
- Navigate to AWS Systems Manager
- Chose the Run Command from the options on the left
- Create a new run command
- Search for the existing PowerShell Run Document
AWS-RunPowerShellScript
- Parameters for Run Command
Document
- 1 (Default)Command parameters
- Copy the contents fromEC2InstancePrep.ps1
file (updated with your parameters)Working Directory
- Leave BlankExecution Timeout
- Leave at 3600Targets
- Choose the instances that were deployed above- Other parameters can be left as default
- (Optionally) Configure an S3 Bucket where Command output will be added
- Execute the Run Command!!
At this point the infrastructure should have been stood up with CDK, the EC2 Instances should have been prepped by the first Run Command in System Manager. It's time to Deploy Some Software.
- Ensure the ArcGIS Enterprise Software has been uploaded to the S3 bucket created by the CDK
- Navigate to AWS Systems Manager
- Chose the Run Command from the options on the left
- Create a new run command
- Search for the existing PowerShell Run Document
AWS-RunPowerShellScript
- Parameters for Run Command
Document
- 1 (Default)Command parameters
- Copy the contents fromInvokeDSC.ps1
file (updated with your parameters)Working Directory
- Leave BlankExecution Timeout
- Change to 28800 (we want to give the commands at least 8 hours to complete)Targets
- Choose ONLY the orchestration instance- Other parameters can be left as default
- (Optionally) Configure an S3 Bucket where Command output will be added
- Execute the Run Command!!
Your all set! Login to the newly deployed ArcGIS Enterprise site using the credentials created in the PowerShell DSC file and the URL specified in your Route53 entries!