7.4 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| intro | Build Infrastructure | gettingstarted-build | With Vault installed, let's dive right into it and start creating some infrastructure. |
Build Infrastructure
With Vault installed, let's dive right into it and start creating some infrastructure.
We'll build infrastructure on AWS for the getting started guide since it is popular and generally understood, but Vault can manage many providers, including multiple providers in a single configuration. Some examples of this are in the use cases section.
If you don't have an AWS account, create one now. For the getting started guide, we'll only be using resources which qualify under the AWS free-tier, meaning it will be free. If you already have an AWS account, you may be charged some amount of money, but it shouldn't be more than a few dollars at most.
~> Warning! If you're not using an account that qualifies under the AWS free-tier, you may be charged to run these examples. The most you should be charged should only be a few dollars, but we're not responsible for any charges that may incur.
Configuration
The set of files used to describe infrastructure in Vault is simply known as a Vault configuration. We're going to write our first configuration now to launch a single AWS EC2 instance.
The format of the configuration files is documented here. Configuration files can also be JSON, but we recommend only using JSON when the configuration is generated by a machine.
The entire configuration is shown below. We'll go over each part
after. Save the contents to a file named example.tf. Verify that
there are no other *.tf files in your directory, since Vault
loads all of them.
provider "aws" {
access_key = "ACCESS_KEY_HERE"
secret_key = "SECRET_KEY_HERE"
region = "us-east-1"
}
resource "aws_instance" "example" {
ami = "ami-408c7f28"
instance_type = "t1.micro"
}
Replace the ACCESS_KEY_HERE and SECRET_KEY_HERE with your
AWS access key and secret key, available from
this page.
We're hardcoding them for now, but will extract these into
variables later in the getting started guide.
This is a complete configuration that Vault is ready to apply. The general structure should be intuitive and straightforward.
The provider block is used to configure the named provider, in
our case "aws." A provider is responsible for creating and
managing resources. Multiple provider blocks can exist if a
Vault configuration is comprised of multiple providers,
which is a common situation.
The resource block defines a resource that exists within
the infrastructure. A resource might be a physical component such
as an EC2 instance, or it can be a logical resource such as
a Heroku application.
The resource block has two strings before opening the block: the resource type and the resource name. In our example, the resource type is "aws_instance" and the name is "example." The prefix of the type maps to the provider. In our case "aws_instance" automatically tells Vault that it is managed by the "aws" provider.
Within the resource block itself is configuration for that resource. This is dependent on each resource provider and is fully documented within our providers reference. For our EC2 instance, we specify an AMI for Ubuntu, and request a "t1.micro" instance so we qualify under the free tier.
Execution Plan
Next, let's see what Vault would do if we asked it to
apply this configuration. In the same directory as the
example.tf file you created, run vault plan. You
should see output similar to what is copied below. We've
truncated some of the output to save space.
$ vault plan
...
+ aws_instance.example
ami: "" => "ami-408c7f28"
availability_zone: "" => "<computed>"
instance_type: "" => "t1.micro"
key_name: "" => "<computed>"
private_dns: "" => "<computed>"
private_ip: "" => "<computed>"
public_dns: "" => "<computed>"
public_ip: "" => "<computed>"
security_groups: "" => "<computed>"
subnet_id: "" => "<computed>"
vault plan shows what changes Vault will apply to
your infrastructure given the current state of your infrastructure
as well as the current contents of your configuration.
If vault plan failed with an error, read the error message
and fix the error that occurred. At this stage, it is probably a
syntax error in the configuration.
The output format is similar to the diff format generated by tools
such as Git. The output has a "+" next to "aws_instance.example",
meaning that Vault will create this resource. Beneath that,
it shows the attributes that will be set. When the value it is
going to is <computed>, it means that the value won't be known
until the resource is created.
Apply
The plan looks good, our configuration appears valid, so it's time to
create real resources. Run vault apply in the same directory
as your example.tf, and watch it go! It will take a few minutes
since Vault waits for the EC2 instance to become available.
$ vault apply
aws_instance.example: Creating...
ami: "" => "ami-408c7f28"
instance_type: "" => "t1.micro"
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
...
Done! You can go to the AWS console to prove to yourself that the EC2 instance has been created.
Vault also put some state into the vault.tfstate file
by default. This state file is extremely important; it maps various
resource metadata to actual resource IDs so that Vault knows
what it is managing. This file must be saved and distributed
to anyone who might run Vault. We recommend simply putting it
into version control, since it generally isn't too large.
You can inspect the state using vault show:
$ vault show
aws_instance.example:
id = i-e60900cd
ami = ami-408c7f28
availability_zone = us-east-1c
instance_type = t1.micro
key_name =
private_dns = domU-12-31-39-12-38-AB.compute-1.internal
private_ip = 10.200.59.89
public_dns = ec2-54-81-21-192.compute-1.amazonaws.com
public_ip = 54.81.21.192
security_groups.# = 1
security_groups.0 = default
subnet_id =
You can see that by creating our resource, we've also gathered a lot more metadata about it. This metadata can actually be referenced for other resources or outputs, which will be covered later in the getting started guide.
Provisioning
The EC2 instance we launched at this point is based on the AMI given, but has no additional software installed. If you're running an image-based infrastructure (perhaps creating images with Packer), then this is all you need.
However, many infrastructures still require some sort of initialization or software provisioning step. Vault supports provisioners, which we'll cover a little bit later in the getting started guide, in order to do this.
Next
Congratulations! You've built your first infrastructure with Vault. You've seen the configuration syntax, an example of a basic execution plan, and understand the state file.
Next, we're going to move on to changing and destroying infrastructure.