Appendix - AWS Deployment Toolbox

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(Link opens in a new window) automates the implementation of the four-node Tableau deployment that is described in Part 4 - Installing and Configuring Tableau Server. 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:

  • 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 .
  • A Step 1 tar backup file is on the EC2 instance where PostgreSQL is installed, as described in Take PostgreSQL Step 1 tar backup.
  • 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.
  • 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(Link opens in a new window) 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. 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.

Sample Terraform templates are available on the Tableau Samples website at https://help.tableau.com/samples/en-us/edg/edg-terraform.zip(Link opens in a new window). 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.

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 .

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(Link opens in a new window)

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(Link opens in a new window) 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 <keyName>.pem

    If you get a warning about private key being accessible by others, then run this command: chmod 600 <keyName.pem> 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.

    Then install, configure, and tar-backup PostgreSQL as described in Part 4 - Installing and Configuring Tableau Server.

    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.

Thanks for your feedback!