Terraform Platforms

AWS (Supported Platform)

This project contains Terraform templates to help you deploy Lattice on Amazon Web Services.

Prerequisites

Configure your virtual environment

Unzip the Lattice bundle, and switch to the terraform/aws/ directory:

unzip lattice-bundle-VERSION.zip
cd lattice-bundle-VERSION/terraform/aws

Rename terraform.tfvars.sample to terraform.tfvars and fill in values with your AWS credentials and desired cluster configuration. Variables available for configuration are:

  • username: Lattice username
  • password: Lattice password
  • aws_access_key_id: AWS access key ID
  • aws_secret_access_key: AWS secret access key
  • aws_ssh_private_key_name: The SSH key name to use for the instances
  • aws_ssh_private_key_path: Path to the SSH private key file
  • aws_region: AWS region (default us-east-1)
  • cell_count: The number of Lattice Cells to launch (default 3)
  • brain_instance_type: Machine type for the Lattice brain (default: t2.medium)
  • cell_instance_type: Machine type for Lattice cells (default: m4.large)
  • ssh_username: SSH user (default ubuntu)
  • vpc_cidr_block: The IPv4 address range that machines in the network are assigned to, represented as a CIDR block (default 10.0.0.0/16)
  • subnet_cidr_block: The IPv4 address range that machines in the network are assigned to, represented as a CIDR block (default 10.0.1.0/24)

Refer to the Terraform AWS provider documentation for more details.

If you would like to fill in these variables without saving them, skip this step. Terraform will let you provide them interactively after running terraform apply.

1. Deploy the cluster to AWS

Run the following commands in the folder containing the terraform.tfvars file:

terraform apply

This will deploy the cluster.

Upon success, Terraform will print the Lattice target:

Outputs:

  password = xxxxxxxx
  target   = x.x.x.x.xip.io
  username = xxxxxxxx

Terraform will also generate a terraform.tfstate file. This file describes the cluster that was built - keep it around in order to modify/tear down the cluster.

2. Download compatible ltc

Follow the instructions below to curl a compatible version of ltc

curl -O http://receptor.$(terraform output target)/v1/sync/<osx|linux>/ltc
chmod +x ltc

Replace <osx|linux> in the URL above with your OS. A Windows executable is also available at http://receptor.local.lattice.cf/v1/sync/windows/ltc.exe.

3. Use the Lattice CLI to target Lattice

Use the Lattice CLI to target the receptor:

./ltc target $(terraform output target)

Notes

The AWS Terraform configs now support Elastic IPs. This means the cluster can be stopped when it’s not in-use (e.g., overnight to save on usage fees), and the Lattice cluster will retain the same target address when the instances are restarted. In order to do this, use the AWS EC2 Console, browse to Instances, and go to Instance State > Stop (or Start when reactivating) on the Lattice instances.

Please Note: There are hourly charges on having an Elastic IP provisioned but not associated to a running instance. More details can be found on AWS Pricing.

DigitalOcean (not available in Lattice v0.6.x)

This project contains Terraform templates to help you deploy Lattice on DigitalOcean.

Prerequisites

Configure

Here are some step-by-step instructions for configuring a Lattice cluster via Terraform:

  1. Visit the Lattice GitHub Releases page
  2. Select the Lattice version you wish to deploy and download the Terraform example file for your target platform. The filename will be lattice.digitalocean.tf
  3. Create an empty folder and place the lattice.digitalocean.tf file in that folder.
  4. Update the lattice.digitalocean.tf by filling in the values for the variables. Details for the values of those variables are below.

The available variables that can be configured are:

  • do_token: Digital Ocean API token
  • do_ssh_public_key_id: SSH public key id. Key ID of your uploaded SSH key.
  • do_ssh_private_key_file: Path to the SSH private key file
  • do_region: The DO region to operate under (default nyc2)
  • do_image: The droplet image ID or slug to base the launched instances (default ubuntu-14-04-x64)
  • do_size_brain: The DO size to use for the Lattice Brain instance (default 512mb)
  • do_size_cell: The DO size to use for the Lattice Cell instances (default 2gb)
  • num_cells: The number of Lattice Cells to launch (default 3)
  • lattice_username: Lattice username (default user)
  • lattice_password: Lattice password (default pass)

Refer to the Terraform DigitalOcean (DO) provider documentation for more details about how to configure the proper credentials.

Getting your SSH Key ID

You can get the key ID by executing an API call against the Digital Ocean API. More info can found on the DigitalOcean API Reference. The token needed for the Authorization: Bearer header is the same as the DigitalOcean API Token referenced in the Prerequisites.

Deploy

Here are some step-by-step instructions for deploying a Lattice cluster via Terraform:

  1. Run the following commands in the folder containing the lattice.digitalocean.tf file
  terraform get -update
  terraform apply

This will deploy the cluster.

Upon success, terraform will print the Lattice target:

Outputs:

  lattice_target = x.x.x.x.xip.io
  lattice_username = xxxxxxxx
  lattice_password = xxxxxxxx

which you can use with the Lattice CLI to ltc target x.x.x.x.xip.io.

Terraform will generate a terraform.tfstate file. This file describes the cluster that was built - keep it around in order to modify/tear down the cluster.

Use

Refer to the Lattice CLI documentation.

Destroy

Destroy the cluster:

terraform destroy

Caveats

When working with Digital Ocean, terraform sometimes gets into an inconsistent state. It is common for the “terraform apply” command to time out while provisioning the VMs, and subsequent terraform commands will then error out. In some cases, a droplet will get stuck in the “New” status (not getting to “Active”), and all Digital Ocean API commands will return:

* Error deleting droplet: Error destroying droplet: API Error: unprocessable_entity: Droplet already has a pending event.

In the event this happens, the recommended avenue is to use the Digital Ocean console to tear down all the droplets, remove the terraform.tfstate file from the current directory, and then run “terraform apply” again to provision from scratch.

Updating

The provided examples (i.e., lattice.digitalocean.tf) are pinned to a specific Bump commit or release tag in order to maintain compatibility between the Lattice build (lattice.tgz) and the Terraform definitions. Currently, Terraform does not automatically update to newer revisions of Lattice.

If you want to update to the latest version of Lattice:
- Update the ref in the source directive of your lattice.digitalocean.tf to master. - Run terraform get -update to update the modules under the .terraform/ folder.

If you want to update to a specific version of Lattice: - Choose a version from either the Bump commits or Releases. - Update the ref in the source directive of your lattice.digitalocean.tf to that version. - Run terraform get -update to update the modules under the .terraform/ folder.

Google Compute Engine (not available in Lattice v0.6.x)

This project contains Terraform templates to help you deploy Lattice on Google Cloud.

Prerequisites

Configure

Here are some step-by-step instructions for configuring a Lattice cluster via Terraform:

  1. Visit the Lattice GitHub Releases page
  2. Select the Lattice version you wish to deploy and download the Terraform example file for your target platform. The filename will be lattice.google.tf
  3. Create an empty folder and place the lattice.google.tf file in that folder.
  4. Update the lattice.google.tf by filling in the values for the variables. Details for the values of those variables are below.

The available variables that can be configured are:

  • gce_account_file: Path to the JSON file used to describe your account credentials, downloaded from Google Cloud Console
  • gce_project: The name of the project to apply any resources to
  • gce_ssh_user: SSH user
  • gce_ssh_private_key_file: Path to the SSH private key file
  • gce_region: The region to operate under (default us-central1)
  • gce_zone: The zone that the machines should be created in (default us-central1-a)
  • gce_ipv4_range: The IPv4 address range that machines in the network are assigned to, represented as a CIDR block (default 10.0.0.0/16)
  • gce_image: The name of the image to base the launched instances (default ubuntu-1404-trusty-v20141212)
  • gce_machine_type_brain: The machine type to use for the Lattice Brain instance (default n1-standard-1)
  • gce_machine_type_cell: The machine type to use for the Lattice Cells instances (default n1-standard-4)
  • num_cells: The number of Lattice Cells to launch (default 3)
  • lattice_username: Lattice username (default user)
  • lattice_password: Lattice password (default pass)

Refer to the Terraform Google Cloud provider documentation for more details about how to configure the proper credentials.

Deploy

Here are some step-by-step instructions for deploying a Lattice cluster via Terraform:

  1. Run the following commands in the folder containing the lattice.google.tf file
  terraform get -update
  terraform apply

This will deploy the cluster.

Upon success, terraform will print the Lattice target:

Outputs:

  lattice_target = x.x.x.x.xip.io
  lattice_username = xxxxxxxx
  lattice_password = xxxxxxxx

which you can use with the Lattice CLI to ltc target x.x.x.x.xip.io.

Terraform will generate a terraform.tfstate file. This file describes the cluster that was built - keep it around in order to modify/tear down the cluster.

Use

Refer to the Lattice CLI documentation.

Destroy

Destroy the cluster:

terraform destroy

Updating

The provided examples (i.e., lattice.google.tf) are pinned to a specific Bump commit or release tag in order to maintain compatibility between the Lattice build (lattice.tgz) and the Terraform definitions. Currently, Terraform does not automatically update to newer revisions of Lattice.

If you want to update to the latest version of Lattice:
- Update the ref in the source directive of your lattice.google.tf to master. - Run terraform get -update to update the modules under the .terraform/ folder.

If you want to update to a specific version of Lattice: - Choose a version from either the Bump commits or Releases. - Update the ref in the source directive of your lattice.google.tf to that version. - Run terraform get -update to update the modules under the .terraform/ folder.

Openstack (not available in Lattice v0.6.x)

This project contains Terraform templates to help you deploy Lattice on Openstack.

Note: This is a community-supplied platform, it is not presently supported by the project maintainers.

Prerequisites

  • An Openstack Cloud
  • An Account, project and relevant access on your openstack cloud.

Configure

Here are some step-by-step instructions for configuring a Lattice cluster via Terraform:

  1. Visit the Lattice GitHub Releases page
  2. Select the Lattice version you wish to deploy and download the Terraform example file for your target platform. The filename will be lattice.openstack.tf
  3. Create an empty folder and place the lattice.openstack.tf file in that folder.
  4. Update the lattice.openstack.tf by filling in the values for the variables. Details for the values of those variables are below.

The available variables that can be configured are:

  • openstack_access_key: Openstack username.
  • openstack_secret_key: Openstack Password.
  • openstack_tenant_name: The Tenant/Project name in Openstack.
  • openstack_key_name: The name given to the SSH key which will be uploaded for use by the instances.
  • openstack_public_key: The actual contents of rsa_id.pub to upload as the public key.
  • openstack_ssh_private_key_file: Path to the SSH private key file (Stays local. Used for provisioning.)
  • openstack_ssh_user: SSH user (default ubuntu)
  • num_cells: The number of Lattice Cells to launch (default 3)
  • openstack_keystone_uri: The Keystone API URL
  • openstack_instance_type_coordinator: flavour for Coordinator node
  • openstack_instance_type_cell: flavour for Cell nodes
  • openstack_neutron_router_gateway_network_id: The UUID of a network which can be used by a Neutron router as a WAN IP address. (Gateway Network)
  • openstack_floating_ip_pool_name: The Name of the Openstack IP pool from which to request floating IP’s
  • openstack_image: The Ubuntu image in glance to use for Instances.
  • openstack_region: Openstack Region. Leave blank to support Openstack installations without region support.
  • lattice_username: Lattice username (default user)
  • lattice_password: Lattice password (default pass)

Refer to the Terraform AWS provider documentation for more details about how to configure the proper credentials.

Deploy

Here are some step-by-step instructions for deploying a Lattice cluster via Terraform:

  1. Run the following commands in the folder containing the lattice.openstack.tf file
  terraform get -update
  terraform apply

This will deploy the cluster.

Upon success, terraform will print the Lattice target:

Outputs:

  lattice_target = x.x.x.x.xip.io
  lattice_username = xxxxxxxx
  lattice_password = xxxxxxxx

which you can use with the Lattice CLI to ltc target x.x.x.x.xip.io.

Terraform will generate a terraform.tfstate file. This file describes the cluster that was built - keep it around in order to modify/tear down the cluster.

Use

Refer to the Lattice CLI documentation.

Destroy

Destroy the cluster:

terraform destroy

Sometimes, destroy will need to be run twice to completely destroy all components, as openstack networking components are often seen as ‘still in use’ when destroyed immidietley after the instances that relied on them.

Updating

The provided examples (i.e., lattice.openstack.tf) are pinned to a specific Bump commit or release tag in order to maintain compatibility between the Lattice build (lattice.tgz) and the Terraform definitions. Currently, Terraform does not automatically update to newer revisions of Lattice.

If you want to update to the latest version of Lattice:
- Update the ref in the source directive of your lattice.openstack.tf to master. - Run terraform get -update to update the modules under the .terraform/ folder.

If you want to update to a specific version of Lattice: - Choose a version from either the Bump commits or Releases. - Update the ref in the source directive of your lattice.openstack.tf to that version. - Run terraform get -update to update the modules under the .terraform/ folder.

Modular. Flexible. Powerful

Application Instances