Amazon Web Services

AttentionThis page documents an earlier version. Go to the latest (v2.1)version.

Prerequisites

  • Download and install terraform.

  • Verify by the terraform command, it should print a help message that looks similar to that shown below.

  1. $ terraform
  1. Usage: terraform [--version] [--help] <command> [args]
  2. ...
  3. Common commands:
  4. apply              Builds or changes infrastructure
  5. console            Interactive console for Terraform interpolations
  6. destroy            Destroy Terraform-managed infrastructure
  7. env                Workspace management
  8. fmt                Rewrites config files to canonical format

1. Create a terraform config file

Create a terraform config file called yugabyte-db-config.tf and add following details to it. The terraform module can be found in the terraform-aws-yugabyte github repository.

  1. provider "aws" {
  2.   # Configure your AWS account credentials here.
  3.   access_key = "ACCESS_KEY_HERE"
  4.   secret_key = "SECRET_KEY_HERE"
  5.   region     = "us-west-2"
  6. }
  8. module "yugabyte-db-cluster" {
  9.   # The source module used for creating AWS clusters.
  10.   source = "github.com/Yugabyte/terraform-aws-yugabyte"
  12.   # The name of the cluster to be created, change as per need.
  13.   cluster_name = "test-cluster"
  15.   # Existing custom security group to be passed so that we can connect to the instances.
  16.   # Make sure this security group allows your local machine to SSH into these instances.
  17.   custom_security_group_id="SECURITY_GROUP_HERE"
  19.   # AWS key pair that you want to use to ssh into the instances.
  20.   # Make sure this key pair is already present in the noted region of your account.
  21.   ssh_keypair = "SSH_KEYPAIR_HERE"
  22.   ssh_key_path = "SSH_KEY_PATH_HERE"
  24.   # Existing vpc and subnet ids where the instances should be spawned.
  25.   vpc_id = "VPC_ID_HERE"
  26.   subnet_ids = ["SUBNET_ID_HERE"]
  28.   # Replication factor of the YugabyteDB cluster.
  29.   replication_factor = "3"
  31.   # The number of nodes in the cluster, this cannot be lower than the replication factor.
  32.   num_instances = "3"
  33. }

NOTE: If you do not have a custom security group, you would need to remove the ${var.custom_security_group_id} variable in main.tf, so that the aws_instance looks as follows:

  1. resource "aws_instance" "yugabyte_nodes" {
  2.   count                       = "${var.num_instances}"
  3.   ...
  4.   vpc_security_group_ids      = [
  5.     "${aws_security_group.yugabyte.id}",
  6.     "${aws_security_group.yugabyte_intra.id}",
  7.     "${var.custom_security_group_id}"
  8.   ]

2. Create a cluster

Init terraform first if you have not already done so.

  1. $ terraform init

Now run the following to create the instances and bring up the cluster.

  1. $ terraform apply

Once the cluster is created, you can go to the URL http://<node ip or dns name>:7000 to view the UI. You can find the node’s ip or dns by running the following:

  1. $ terraform state show aws_instance.yugabyte_nodes[0]

You can access the cluster UI by going to any of the following URLs.

You can check the state of the nodes at any point by running the following command.

  1. $ terraform show

3. Verify resources created

The following resources are created by this module:

  • module.yugabyte-db-cluster.aws_instance.yugabyte_nodes The AWS instances.

For cluster named test-cluster, the instances will be named yb-ce-test-cluster-n1, yb-ce-test-cluster-n2, yb-ce-test-cluster-n3.

  • module.yugabyte-db-cluster.aws_security_group.yugabyte The security group that allows the various clients to access the YugabyteDB cluster.

For cluster named test-cluster, this security group will be named yb-ce-test-cluster with the ports 7000, 9000, 9042 and 6379 open to all other instances in the same security group.

  • module.yugabyte-db-cluster.aws_security_group.yugabyte_intra The security group that allows communication internal to the cluster.

For cluster named test-cluster, this security group will be named yb-ce-test-cluster-intra with the ports 7100, 9100 open to all other instances in the same security group.

  • module.yugabyte-db-cluster.null_resource.create_yugabyte_universe A local script that configures the newly created instances to form a new YugabyteDB universe.

4. Destroy the cluster (optional)

To destroy what we just created, you can run the following command.

  1. $ terraform destroy