mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# Template: Using Terraform to Provision an Ubuntu Machine on AWS
|
|
|
|
If you didn't read the introduction to the [cloud deployment templates](index.html), please do that now. The main point is that they're not for deploying a production node; they can be used as a starting point.
|
|
|
|
This page explains a way to use [Terraform](https://www.terraform.io/) to provision an Ubuntu machine (i.e. an EC2 instance with Ubuntu 16.04) and other resources on [AWS](https://aws.amazon.com/). That machine can then be used to host a one-machine BigchainDB node.
|
|
|
|
|
|
## Install Terraform
|
|
|
|
The [Terraform documentation has installation instructions](https://www.terraform.io/intro/getting-started/install.html) for all common operating systems.
|
|
|
|
If you don't want to run Terraform on your local machine, you can install it on a cloud machine under your control (e.g. on AWS).
|
|
|
|
Note: Hashicorp has an enterprise version of Terraform called "Terraform Enterprise." You can license it by itself or get it as part of Atlas. If you decide to license Terraform Enterprise or Atlas, be sure to install it on your own hosting (i.e. "on premise"), not on the hosting provided by Hashicorp. The reason is that BigchainDB clusters are supposed to be decentralized. If everyone used Hashicorp's hosted Atlas, then that would be a point of centralization.
|
|
|
|
**Ubuntu Installation Tips**
|
|
|
|
If you want to install Terraform on Ubuntu, first [download the .zip file](https://www.terraform.io/downloads.html). Then install it in `/opt`:
|
|
```text
|
|
sudo mkdir -p /opt/terraform
|
|
sudo unzip path/to/zip-file.zip -d /opt/terraform
|
|
```
|
|
|
|
Why install it in `/opt`? See [the answers at Ask Ubuntu](https://askubuntu.com/questions/1148/what-is-the-best-place-to-install-user-apps).
|
|
|
|
Next, add `/opt/terraform` to your path. If you use bash for your shell, then you could add this line to `~/.bashrc`:
|
|
```text
|
|
export PATH="/opt/terraform:$PATH"
|
|
```
|
|
|
|
After doing that, relaunch your shell or force it to read `~/.bashrc` again, e.g. by doing `source ~/.bashrc`. You can verify that terraform is installed and in your path by doing:
|
|
```text
|
|
terraform --version
|
|
```
|
|
|
|
It should say the current version of Terraform.
|
|
|
|
|
|
## Get Set Up to Use Terraform
|
|
|
|
First, do the [basic AWS setup steps outlined in the Appendices](../appendices/aws-setup.html).
|
|
|
|
Then go to the `.../bigchaindb/ntools/one-m/aws/` directory and open the file `variables.tf`. Most of the variables have sensible default values, but you can change them if you like. In particular, you may want to change `aws_region`. (Terraform looks in `~/.aws/credentials` to get your AWS credentials, so you don't have to enter those anywhere.)
|
|
|
|
The `ssh_key_name` has no default value, so Terraform will prompt you every time it needs it.
|
|
|
|
To see what Terraform will do, run:
|
|
```text
|
|
terraform plan
|
|
```
|
|
|
|
It should ask you the value of `ssh_key_name`.
|
|
|
|
It figured out the plan by reading all the `.tf` Terraform files in the directory.
|
|
|
|
If you don't want to be asked for the `ssh_key_name`, you can change the default value of `ssh_key_name` (in the file `variables.tf`) or [you can set an environmen variable](https://www.terraform.io/docs/configuration/variables.html) named `TF_VAR_ssh_key_name`.
|
|
|
|
|
|
## Use Terraform to Provision Resources
|
|
|
|
To provision all the resources specified in the plan, do the following. **Note: This will provision actual resources on AWS, and those cost money. Be sure to shut down the resources you don't want to keep running later, otherwise the cost will keep growing.**
|
|
```text
|
|
terraform apply
|
|
```
|
|
|
|
Terraform will report its progress as it provisions all the resources. Once it's done, you can go to the Amazon EC2 web console and see the instance, its security group, its elastic IP, and its attached storage volumes (one for the root directory and one for RethinkDB storage).
|
|
|
|
At this point, there is no software installed on the instance except for Ubuntu 16.04 and whatever else came with the Amazon Machine Image (AMI) specified in the Terraform configuration (files).
|
|
|
|
The next step is to install, configure and run all the necessary software for a BigchainDB node. You could use [our example Ansible playbook](template-ansible.html) to do that.
|
|
|
|
|
|
## Optional: "Destroy" the Resources
|
|
|
|
If you want to shut down all the resources just provisioned, you must first disable termination protection on the instance:
|
|
|
|
1. Go to the EC2 console and select the instance you just launched. It should be named `BigchainDB_node`.
|
|
2. Click **Actions** > **Instance Settings** > **Change Termination Protection** > **Yes, Disable**
|
|
3. Back in your terminal, do `terraform destroy`
|
|
|
|
Terraform should "destroy" (i.e. terminate or delete) all the AWS resources you provisioned above.
|
|
|
|
If it fails (e.g. because of an attached and mounted EBS volume), then you can terminate the instance using the EC2 console: **Actions** > **Instance State** > **Terminate** > **Yes, Terminate**. Once the instance is terminated, you should still do `terraform destroy` to make sure that all the other resources are destroyed.
|
|
|