Sandbox Deployment

Environment Setup

DANGER

Sandbox deployment scripts should not be used in production or for scaffolding infrastructure to be used in production.

To create and use an Xiid Sandbox Domain, you will need to set up your computer and AWS account with the appropriate tools and configurations necessary for the Sandbox deployment.

AWS CLI Setup

TIP

If using macOS, this step is not required. The macOS version of the Xiid Domain Sandbox Tools installs required dependencies automatically.

The Amazon Web Services Command Line Interface (AWS CLI) allows users to interact with AWS resources using the command prompt or terminal. The AWS CLI operates as the “engine” behind Terraform, driving the deployment commands to your AWS account.

Download the AWS CLI here, open the installer, and follow the prompts.

After the installation is complete, you can open a command prompt or Terminal window and run aws. If a list of available AWS commands is displayed, you have successfully installed the AWS CLI.

AWS IAM User Setup

For the Xiid Domain Sandbox Tools to be able to stand up and destroy Xiid Sandbox infrastructure in your AWS account on your behalf, you must generate an IAM User with the AdministratorAccess policy and have its associated Access Key and Secret Key, which will be used in future steps.

View Step-by-Step Instructions

First, sign in to the AWS Console.

After signing in, navigate to IAM (Identity and Access Management) by clicking the black search bar in the top left, typing IAM, and selecting it from the list.

Click on Users on the left side navigation panel.

On the Users screen, click the blue Add users button in the top right.

Provide a username for your new user, leave the Provide user access to the AWS Management Console box unchecked, and click the orange Next button.

On the Set Permissions screen, click the Attach policies directly box near the top.

Select the AdministratorAccess policy and click the orange Next button.

Enter any tags you wish to associate with your user (this is optional and purely for your organizational purposes), and then click Next.

Review your new user information, and if it all looks correct, click the orange Create User button.

Now, you will be taken back to the Users screen. Click the new user you just created, and select the Security credentials tab below the Summary box.

Scroll down to the Access keys section and click Create Access Key.

Select the Command Line Interface (CLI) option, select the checkbox next to I understand the above recommendation and want to proceed to create an access key, and click the orange Next button.

Enter any tags you wish to associate with your access key (this is optional), and then click Create Access Key.

The next screen will display your Access Key and Secret Key for the user.

Click the Download .csv file button above the table of new users to download the Access Key and Secret Key to your computer.

Do not lose track nor give away (privately or publicly) the access key, secret key, or csv file.

Later, after Xiid's scripts have finished deploying your infrastructure, you may (but are not required to) delete this IAM user. If you delete the IAM user, you must re-create it before tearing down the infrastructure.

If you choose to re-create the user, you will need to open a command prompt or Terminal window, run aws configure, and enter your new Access Key and Secret Keybefore running any infrastructure teardown commands or scripts.

Script-Based Sandbox Deployment

The following steps will help you get your workspace and infrastructure set up and deployed correctly.

Start by obtaining the Xiid Domain Sandbox Tools zip file from Xiid and unzipping it in a safe location.

Infastructure Deployment

WARNING

Make sure to follow these steps on the computer you're going to deploy the sandbox from.

Windows Point-and-Click:

Double-click the deploy_sandbox.bat file to deploy your sandbox environment to AWS.

Please note that if you choose this option, you are accepting the default values for ip_address and deploy_region which are 0.0.0.0/0 and us-west-1 respectively.

Command-Line Deployments:

TIP

On macOS, the script will automatically prompt you to install required dependencies.
On Windows and Linux, Terraform must be installed along with the AWS CLI.

From a command prompt or Terminal window, navigate to the installer directory and run the following command:

Windows

deploy_sandbox.bat

macOS

./deploy_sandbox_macos.sh

Linux

./deploy_sandbox_linux.sh

By default, the values for ip_address and deploy_region are 0.0.0.0/0 and us-west-1 respectively.

If you wish to customize these, you can specify one or more of several flags to the Sandbox deployment scripts, but these must be provided in order and none may be skipped:

• ip_address: The IPv4 IP Address to restrict RDP access to only your computer.
• deploy_region: The region to deploy your infrastructure in.
• rdp_count: The number of RDP Instances to deploy in your infrastructure.

As an example, a custom deploy command with arguments would look like:

Windows

deploy_sandbox.bat 0.0.0.0/0 us-west-2 3

macOS

./deploy_sandbox_macos.sh 0.0.0.0/0 us-west-2 3

Linux

./deploy_sandbox_linux.sh 0.0.0.0/0 us-west-2 3

While Running the Sandbox Tools:

While running the sandbox deployment script for your operating system, you will be prompted for your Access Key and Secret Key. Enter those values obtained during AWS IAM User Setup. You can hit enter to skip the prompts for region and output format.

Several Terraform commands will be run under the hood, and some will require your confirmation.

When prompted that there are Plans to Add, enter yes to execute the infrastructure deployment.

After your infrastructure has been provisioned, you will see an Apply complete! or press any key to continue… message.

DANGER

Do not delete, modify, or move the terraform.tfstate or terraform.tfstate.backup files generated during deployment. These files are used by Terraform to keep track of the infrastructure you just deployed and are necessary to tear it down when you are finished using it.

Infrastructure Validation

After provisioning, it will usually take a few minutes for the resources to be fully booted-up and available.

Although the deployment scripts are reliable, you can manually verify that the infrastructure is fully stood up and ready to go.

View Step-by-Step Instructions

Signing in to the AWS Console.

Be sure to select the region in the top right corner that you chose when running the Sandbox Tools (the default region is us-west-1).

Navigate to EC2 and click the Instances menu item on the left side of the console.

You should see two EC2 instances available in the EC2 console: one named SandboxDomainController and one named SandboxRDP.

Verify that there is a green checkmark listed under the Status Check column before attempting to access your instances.

The following are descriptions of the resources created for the Sandbox Domain:

• Terraform:
  • Required Version: >= 0.14.9
• Provider:
  • Source: hashicorp/aws
  • Version: ~> 3.27
• VPC:
  • CIDR Block: 172.29.0.0./16
  • Name: SandboxDomainVPC
• Subnet:
  • CIDR Block: 172.29.0.0/16
  • Map Public IP on Launch: true
  • Name: SandboxDomainSubnet
• Internet Gateway:
  • Name: SandboxDomainInternetGateway
• Route Table:
  • Route:
    • CIDR Block: 0.0.0.0/0
  • Name: SandboxDomainRouteTable
• Security Group:
  • Group Name: sandbox_domain_security_group
  • Ingress:
    • From Port: 0
    • To Port: 0
    • Protocol: -1 (All)
    • CIDR Block: 172.29.0.0/16
  • Ingress:
    • From Port: 3389
    • To Port: 3389
    • Protocol: tcp
    • CIDR Block: [0.0.0.0/0 by default, override by ip_address var]
  • Egress:
    • From Port: 0
    • To Port: 0
    • Protocol: -1 (All)
    • CIDR Block: 0.0.0.0/0
  • Name: SandboxSecurityGroup
• Domain Controller:
  • AMI: OneOf(DC Images)
  • Instance Type: t2.medium
  • Disk Size: 100 GB
  • Name: SandboxDomainController
• RDP Instance:
  • AMI: OneOf(RDP Images)
  • Instance Type: t2.medium
  • Disk Size: 50 GB
  • Name: SandboxRDPInstance

If you encounter any issues with deployment, let us know.

Manual Sandbox Deployment

If you do not wish to use the automated scripts, you can use Terraform directly to deploy your sandbox environment.

View Step-by-Step Instructions

Start by creating a new folder. For this guide, we will call that folder sandbox. Copy the main.tf script file to your sandbox directory.

Next, open a command prompt or Terminal window and navigate to the sandbox directory.

Run aws configure.

The AWS CLI will prompt you for your Access Key, Secret Key, and Region. Skip the Region prompt by pressing enter, as this will be later specified by Terraform.

Ensure that Terraform is properly installed by running terraform -h or terraform -version. If not, install it.

Run terraform init. You should receive a message saying: Terraform has beensuccessfully initialized!

Run terraform apply. This will build and display an execution graph of the infrastructure to set up.

You can specify three variables to override in the Terraform script:

• ip_address: Specify your IPv4 IP Address to restrict RDP access to only your computer. Default value is: 0.0.0.0/0 (any IP address can RDP to the machine with the admin username/password)
  • To override the ip_address variable, add: -var ip_address={your_ip_address}
• deploy_region: Specify a region to deploy your infrastructure into. Default value is: us-west-1
  • To override the deploy_region variable, add: -var deploy_region={region_to_deploy}
• rdp_count: Specify the number RDP Instances to launch alongside your Domain Controller.
  • To override the rdp_count variable, add: -var rdp_count={number_of_instances}
• The full command could look like this: terraform apply -var ip_address=0.0.0.0/0 -var deploy_region=us-west-2 -var rdp_count=3

After running the terraform apply command with relevant flags, verify that there are a minimum of 8 Plans to add, and then type yes to confirm. You can also check the execution graph in the console to verify the infrastructure that will be created.

Refer to the Infrastructure Validation section to verify that the Sandbox was properly deployed.

When you are ready to tear down your infrastructure, run terraform destroy.

If you deployed your sandbox domain in a region other than the default region (us-west-1), you will need to provide the region to the destroy command as such:

terraform destroy var deploy_region={your_region}

i.e. terraform destroy var deploy_region=us-west-2

Infrastructure Tear Down

WARNING

If you lost the terraform.tfstate or terraform.tfstate.backup files, you will not be able to automatically tear down your infrastructure and must manually delete the infrastructure from the AWS Console.

Windows

When you are done using your Sandbox and would like to tear it down, double-click the destroy_sandbox.bat file that was generated when running the deploy_sandbox.bat script.

Terraform will print a destruction plan for your resources. Enter yes to execute the tear down.

macOS and Linux

On macOS and Linux, instructions for infrastructure teardown are outputted to a file named cleanup_instructions.txt.

Following the simple instructions in the text file should successfully de-provision resources used for the Xiid Sandbox.