--- schema_version: "1" id: 97a5710f664f8c402f5a7c536bd07b54585ebf59442419c5e69bba0a1c4ee601 title: Appendix - AWS Deployment Toolbox collection: tableau version: current locale: en-us portal_url: https://docs.salesforce.com/tableau/current/en-us/guides/enterprise-deployment/edg_part_app-aws.md canonical_url: https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part_app-aws.htm source_site: help.tableau.com content_type: documentation content_hash: 31796818d5590125fb9e00be7d0e373c93e3296351f1ed8a8790e78a2e6499a3 description: AWS deployment toolbox with the TabDeploy4EDG script and Terraform automation examples. --- [Skip to main content](#main-content) # Appendix - AWS Deployment Toolbox **Note**: Tableau no longer updates the Enterprise Deployment Guide. Although we still recommend the reference architecture described here as a valid deployment model for Tableau Server in AWS, specific configuration procedures may have changed since the last update. Always cross-reference these steps with the latest [Tableau Server Help](https://help.tableau.com/current/server/en-us/get_started_server.htm) documentation to ensure accuracy. This topic includes tools and alternate deployment options for the reference architecture when deployed in AWS. Specifically, this topic describes how to automate the example AWS deployment that is described throughout the EDG. ## TabDeploy4EDG automated installation script The [TabDeploy4EDG script](https://help.tableau.com/samples/en-us/edg/tabdeploy4edg.txt) automates the implementation of the four-node Tableau deployment that is described in [Part 4 - Installing and Configuring Tableau Server](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm). If you are following the example AWS implementation as described in this Guide, then you may be able to run TabDeploy4EDG. **Requirements.** To run the script, you must prepare and configure the AWS environment according to the example implementation in [Part 3 - Preparing for Tableau Server Enterprise Deployment](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part3.htm): - VPC, subnet, and security groups have been configured as described. IP addresses do not have to match those that are shown in the example implementation. - Four EC2 instances running the latest, updated builds of AWS Linux 2 - PostgreSQL is installed and has been configured as described in [Install, configure, and tar PostgreSQL](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm#Install,) . - A Step 1 tar backup file is on the EC2 instance where PostgreSQL is installed, as described in [Take PostgreSQL Step 1 tar backup](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm#Take). - The EC2 instance that will be running Node 1 of the Tableau Server deployment has been configured to communicate with PostgreSQL as described in [Part 4 - Installing and Configuring Tableau Server](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm#Configur). - You have logged into each EC2 instance with an SSH session from the bastion host. The script takes about 1.5-2 hours to install and configure the four Tableau servers. The script configures Tableau according to the prescribed settings of the reference architecture. The script performs the following actions: - Restores Stage 1 backup of PostgreSQL host if you specify a path to the PostgreSQL host's tar file. - Obliterates existing Tableau installations on all nodes. - Runs `sudo yum update` on all nodes. - Downloads and copies Tableau rpm package to each node. - Downloads and installs dependencies to each node. - Creates `/app/tableau_server` and installs package on all nodes. - Installs Node 1 with a local identity store and configures external repository with PostgreSQL. - Performs bootstrap installation and initial configuration of Node 2- Node 4. - Deletes the bootstrap file and the configuration file for TabDeploy4EDG. - Configures services across the Tableau cluster according to reference architecture specifications. - Validates installation and returns status for each node. **Download and copy the script to the bastion host** 1. Copy the script from the [TabDeploy4EDG samples page](https://help.tableau.com/samples/en-us/edg/tabdeploy4edg.txt) and paste the code into a file called, `TabDeploy4EDG`. 2. Save the file to the home directory on the EC2 host that is serving as the bastion host. 3. Run the following command to change the mode on the file to make it executable: sudo chmod +x TabDeploy4EDG **Run TabDeploy4EDG** TabDeploy4EDG must be run from the bastion host. The script has been written with the assumption that you are running under the context of ssh forward agent as described at [Example: Connect to bastion host in AWS](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part3.htm#Example:). If you are not running with ssh forward agent context, then you will be prompted for passwords throughout the installation process. 1. Create, edit, and save a registration file (`registration.json`). The file must be a properly-formatted json file. Copy and customize the following template: { "zip" : "97403", "country" : "USA", "city" : "Springfield", "last\_name" : "Simpson", "industry" : "Energy", "eula" : "yes", "title" : "Safety Inspection Engineer", "phone" : "5558675309", "company" : "Example", "state" : "OR", "department" : "Engineering", "first\_name" : "Homer", "email" : "homer@example.com" } 2. Run the following command to generate a template configuration file: ./TabDeploy4EDG -g edg.config 3. Open the configuration file to edit: sudo nano edg.config At a minimum, you must add the IP addresses of each EC2 host, a file path to the registration file, and a valid license key. 4. When you are done editing the configuration file, save it, and then close it. 5. To run TabDeploy4EDG, run the following command: ./TabDeploy4EDG -f edg.config ## Example: Automate AWS infrastructure deployment with Terraform This section describes how to configure and run Terraform to deploy the EDG reference architecture in AWS. The example Terraform configuration presented here deploys an AWS VPC with the subnets, security groups, and EC2 instances that are described in [Part 3 - Preparing for Tableau Server Enterprise Deployment](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part3.htm). Sample Terraform templates are available on the Tableau Samples website at [https://help.tableau.com/samples/en-us/edg/edg-terraform.zip](https://help.tableau.com/samples/en-us/edg/edg-terraform.zip). These templates must be configured and customized for your organization. The configuration content provided in this section describes the minimum required template changes you must customize to deploy. ### Goal The Terraform templates and content provided here are intended to provide a working sample that will allow you to deploy EDG quickly in a development test environment. We've made a best effort to test and document the example Terraform deployment. However, using Terraform to deploy and maintain EDG in a production environment will require Terraform expertise that is beyond the scope of this example. Tableau does not provide support for the example Terraform solution documented here. ### End state Follow the procedure in this section to set up a VPC in AWS that is functionally equivalent to the VPC that is specified in [Part 3 - Preparing for Tableau Server Enterprise Deployment](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part3.htm). ![A diagram of an AWS architecture for Tableau Server.](/tableau/current/en-us/guides/enterprise-deployment/en-us/Img/edg-vpc-terraform.png) The sample Terraform templates and supporting content in this section: - Creates a VPC with an elastic IP address, two availability zones, and subnets organization as shown above (IP addresses are different) - Creates the Bastion, Public, Private, and Data security groups. - Sets most ingress and egress rules on the security groups. You will need to edit security groups after Terraform runs. - Creates the following EC2 hosts (each running AWS Linux2): bastion, proxy 1 proxy 2, Tableau node 1, Tableau node 2, Tableau node 3, Tableau node 4. - EC2 hosts for PostgreSQL are not created. You must create the EC2 manually in the Data security group, and then install and configure PostgreSQL as described in [Install, configure, and tar PostgreSQL](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm#Install,) . ### Requirements - AWS account - you must have access to an AWS account that allows you to create VPCs. - If you are running Terraform from a Windows computer, you will need to install AWS CLI. - An available elastic IP address in your AWS account. - A domain that is registered in AWS Route 53. Terraform will create a DNS zone and related SSL certificates in Route 53. Therefore, the profile under which Terraform runs, must also have appropriate permissions in Route 53. ### Before you begin - The command line examples in this procedure are for Terminal with Apple OS. If you are running Terraform on Windows you may need to adapt commands with file paths as appropriate. - A Terraform project is made up of many text configuration files (.tf file extension). You configure Terraform by customizing these files. If you do not have a robust text editor, install Atom or Text++. - If you are sharing the Terraform project with others, we recommend storing the project in Git for change management. ### Step 1 - Prepare environment #### A. Download and install Terraform [https://www.terraform.io/downloads](https://www.terraform.io/downloads) #### B. Generate private-public key pair This is the key that you will use to access AWS and the resulting VPC environment. When you run Terraform, you’ll include the public key. Open Terminal and run the following commands: 1. Create a private key. For example, `my-key.pem`: openssl genrsa -out my-key.pem 1024 2. Create a public key. This key format is not used for Terraform. You will convert it to a ssh key later in this procedure: openssl rsa -in my-key.pem -pubout > my-key.pub 3. Set permissions on the private key: sudo chmod 0600 my-key.pem To set permissions on Windows: - Locate the file in Windows Explorer, right-click on it then select Properties. Navigate to the Security tab and then click Advanced. - Change the owner to you, disable inheritance and delete all permissions. Grant yourself Full control and then click Save. Mark the file as read-only. 4. Create ssh public key. This is the key you’ll copy into Terraform later in the process. ssh-keygen -y -f my-key.pem >my-key-ssh.pub #### C. Download project and add state directory 1. Download and unzip the [EDG Terraform project](https://help.tableau.com/samples/en-us/edg/edg-terraform.zip) and save them to your local computer. After you unzip the download you’ll have a top-level directory, edg-terraform, and a series of subdirectories. 2. Create a directory called `state`, as a peer to the top-level `edg-terraform` directory. ### Step 2: Customize the Terraform templates You must customized the Terraform templates to suit your AWS and EDG environment. The example here provides the minimum template customizations that most organization will need to make. It's likely that your particular environment will require other customizations. This section is organized by template name. Be sure to save all changes before proceeding to _Step 3 - Run Terraform_. #### versions.tf There are three instances of `versions.tf` files where the `required_version` field must match the version of terraform.exe you're using. Check the version of terraform (`terraform.exe -version`) and update each of the following instances: - `edg-terraform\versions.tf` - `edg-terraform\modules\proxy\versions.tf` - `edg-terraform\modules\tableau_instance\versions.tf` #### key-pair.tf 1. Open the public key that you generated in Step 1B and copy the key: less my-key-ssh.pub Windows: Copy the contents of your public key. 2. Copy the public key string into the public\_key argument, for example: resource "aws\_key\_pair" "tableau" { key\_name = "my-key" public\_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQ (truncated example) dZVHambOCw==" Ensure that the `key_name` value is unique in the datacenter or `terraform apply` will fail. #### locals.tf Update `user.owner` to your name or alias. The value you enter here will be used for the "Name" tag in AWS on the resources that Terraform creates. #### providers.tf 1. Add tags per your organization's requirements. For example: default\_tags { tags = { "Application" = "tableau", "Creator" = "alias@example.com", "DeptCode" = "8675309", "Description" = "EDG", "Environment" = "test", "Group" = "itcloud@example.com" } } 2. If using `provider`, comment out the `assume_role` lines: /\* assume\_role { role\_arn = "arn:aws:iam::310946706895:role/terraform-backend" session\_name = "terraform" }\*/ #### elb.tf Under `'resource "aws_lb" "tableau" {'` choose a unique value to use for `name` and `tags.Name`. If another AWS load balancer has the same name in the datacenter, then `terraform apply` will fail. Add `idle_timeout`: resource "aws\_lb" "tableau" { name = "edg-again-alb" load\_balancer\_type = "application" subnets = \[for subnet in aws\_subnet.public : subnet.id\] security\_groups = \[aws\_security\_group.public.id\] drop\_invalid\_header\_fields = true idle\_timeout = 400 tags = { Name = "edg-again-alb" } } #### variables.tf Update root domain name. This name must match the domain that you have registered in Route 53. variable "root\_domain\_name" { default = "example.com" } By default, the subdomain, `tableau`, is specified for the VPC DNS domain name. To change this, update `subdomain`: variable "subdomain" { default = "tableau" } #### modules/tableau\_instance/ec2.tf There are two ec2.tf files in the project. This customization is for the Tableau instance of the ec2.tf in the directory: `modules/tableau_instance/ec2.tf`. - If required, add tags blob: tags = { "Name" : var.ec2\_name, "user.owner" = "ALIAS", "Application" = "tableau", "Creator" = "ALIAS@example.com", "DeptCode" = "8675309", "Description" = "EDG", "Environment" = "test", "Group" = "itcloud@example.com" } } - As needed, optionally update your storage to handle your data requirements: Root volume: root\_block\_device { volume\_size = 100 volume\_type = "gp3" } Application volume: resource "aws\_ebs\_volume" "tableau" { availability\_zone = data.aws\_subnet.tableau.availability\_zone size = 500 type = "gp3" } ### Step 3 - Run Terraform #### A. Initialize Terraform In Terminal, change to the `edg-terraform` directory and run the following command: terraform init If initialization is successful continue to the next step. If initialize failed, follow the instructions in the Terraform output. #### B. Plan Terraform From the same directory, run the plan command: terraform plan This command can be run multiple times. Run as many times as needed to fix errors. When this command runs error free continue to the next step. #### C. Apply Terraform From the same directory run the apply command: terraform apply Terraform will prompt you to verify deployment, type `Yes`. #### Optional: Destroy Terraform You can destroy the entire VPC by running the destroy command: terraform destroy The destroy command will only destroy what it has created. If you have made manual changes to some objects in AWS (i.e., security groups, subnets, etc), then the `destroy` will fail. To exit out of a failing/hanging destroy operation, type `Control + C`. You must then clean up the VPC manually to the state where it was when Terraform originally created it. You can then run the `destroy` command. ### Step 4 - Connect to bastion All command line connection is through the bastion host on TCP 22 (SSH protocol). 1. In AWS create an inbound rule in the bastion security group (**AWS** \> **Security Groups** > **Bastion SG** > **Edit inbound rules**) and create a rule to allow SSH (TCP 22) connections from the IP address or subnet mask where you will be running Terminal commands. Optional: You may find it helpful to allow file copying between the EC2 instances in the Private and Public groups during deployment. Create inbound SSH rules: - Private: create inbound rule to allow SSH from Public - Public: create inbound rule to allow SSH from Private and from Public 2. Use the pem key that you created in Step 1.B to connect to the bastion host: **On Mac terminal:** Run the following commands from the directory where the pem key is stored: ssh-add —apple-use-keychain .pem If you get a warning about private key being accessible by others, then run this command: `chmod 600 ` and then run the `ssh-add` command again. Connect to the bastion host with this command: `ssh -A ec2-user@IPaddress` For example: `ssh -A ec2-user@3.15.12.112`. **On Windows using PuTTY and Pageant:** 1. Create ppk from pem key: Use PuTTY Key Generator. Load the pem key that you created in Step 1.B. After the key imports, click **Save private key**. This creates a ppk file. 2. In PuTTY - open configuration and make the following changes: - Sessions>Host Name: add IP address of bastion host. - Sessions>Port: 22 - Connection>Data>Auto-login username: ec2-user - Connection>SSH>Auth>Allow agent forwarding - Connection>SSH>Auth> For private key, click Browse and select the .ppk file that you just created. 3. Install Pageant and load the ppk into the application. ### Step 5 -Install PostgreSQL The Terraform template does not install PostgreSQL for use as the external repository. However, the associated security group and subnet is created. If you will be installing the external repository on an EC2 instance running PostgreSQL, then you must deploy the EC2 instance as described in [Part 3 - Preparing for Tableau Server Enterprise Deployment](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part3.htm). Then install, configure, and tar-backup PostgreSQL as described in [Part 4 - Installing and Configuring Tableau Server](https://help.tableau.com/current/guides/enterprise-deployment/en-us/edg_part4.htm). ### Step 6 - (Optional) Run DeployTab4EDG The TabDeploy4EDG script automates the implementation of the four-node Tableau deployment that is described in Part 4. See [TabDeploy4EDG automated installation script](#EDGSetup).