website: build/provision
This commit is contained in:
Mitchell Hashimoto
parent
b2b85d460f
commit
bbb8dd774a
|
|
@ -0,0 +1,167 @@
|
||||||
|
---
|
||||||
|
layout: "intro"
|
||||||
|
page_title: "Build an Image"
|
||||||
|
prev_url: "/intro/getting-started/setup.html"
|
||||||
|
next_url: "/intro/getting-started/provision.html"
|
||||||
|
next_title: "Provision"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Build an Image
|
||||||
|
|
||||||
|
With Packer installed, let's just dive right into it and build our first
|
||||||
|
image. Our first image will be an [Amazon EC2 AMI](http://aws.amazon.com/ec2/)
|
||||||
|
with Redis pre-installed. This is just an example. Packer can create images
|
||||||
|
for [many platforms](/intro/platforms.html) with anything pre-installed.
|
||||||
|
|
||||||
|
If you don't have an AWS account, [create one now](http://aws.amazon.com/free/).
|
||||||
|
For the example, we'll use a "t1.micro" instance to build our image, which
|
||||||
|
qualifies under the AWS [free-tier](http://aws.amazon.com/free/), 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 cents.
|
||||||
|
|
||||||
|
<div class="alert alert-block alert-warn">
|
||||||
|
<strong>Note</strong> that if you're not using an account that qualifies under
|
||||||
|
the AWS <a href="http://aws.amazon.com/free/">free-tier</a>, you may be
|
||||||
|
charged to run these examples. The charge should only be a few cents, but
|
||||||
|
we're not responsible if it ends up being more.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
Packer can build images for [many platforms](/intro/platforms.html) other than
|
||||||
|
AWS, but AWS requires no additional software installed on your computer and
|
||||||
|
their [free-tier](http://aws.amazon.com/free/) makes it free to use for most
|
||||||
|
people. This is why we chose to use AWS for the example. If you're uncomfortable
|
||||||
|
setting up an AWS account, feel free to follow along as the basic principles
|
||||||
|
apply to the other platforms as well.
|
||||||
|
|
||||||
|
## The Template
|
||||||
|
|
||||||
|
The configuration file used to define what image we want built and how
|
||||||
|
is called a _template_ in Packer terminology. The format of a template
|
||||||
|
is simple [JSON](http://www.json.org/). JSON struck the best balance between
|
||||||
|
human-editable and machine-editable, allowing both hand-made templates as well
|
||||||
|
as machine generated templates to easily be made.
|
||||||
|
|
||||||
|
We'll start by creating the entire template, then we'll go over each section
|
||||||
|
briefly. Create a file `example.json` and fill it with the following contents:
|
||||||
|
|
||||||
|
<pre class="prettyprint">
|
||||||
|
{
|
||||||
|
"builders": [{
|
||||||
|
"type": "amazon-ebs",
|
||||||
|
"access_key": "YOUR KEY HERE",
|
||||||
|
"secret_key": "YOUR SECRET KEY HERE",
|
||||||
|
"region": "us-east-1",
|
||||||
|
"source_ami": "ami-de0d9eb7",
|
||||||
|
"instance_type": "t1.micro",
|
||||||
|
"ssh_username": "ubuntu",
|
||||||
|
"ami_name": "packer-example {{.CreateTime}}"
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
Please fill in the `access_key` and `secret_key` with the proper values
|
||||||
|
for your account. Your security credentials can be found on
|
||||||
|
[this page](https://console.aws.amazon.com/iam/home?#security_credential).
|
||||||
|
|
||||||
|
This is a basic template that is ready-to-go. It should be immediately recognizable
|
||||||
|
as a normal, basic JSON object. Within the object, the `builders` section
|
||||||
|
contains an array of JSON objects configuring a specific _builder_. A
|
||||||
|
builder is a component of Packer that is responsible for creating a machine
|
||||||
|
and turning that machine into an image.
|
||||||
|
|
||||||
|
In this case, we're only configuring a single builder of type `amazon-ebs`.
|
||||||
|
This is the Amazon EC2 AMI builder that ships with Packer. This builder
|
||||||
|
builds an EBS-backed AMI by launching a source AMI, provisioning on top of
|
||||||
|
that, and re-packaging it into a new AMI.
|
||||||
|
|
||||||
|
The additional keys within the object are configuration for this builder, specifying things
|
||||||
|
such as access keys, the source AMI to build from, and more.
|
||||||
|
The exact set of configuration variables available for a builder are
|
||||||
|
specific to each builder and can be found within the [documentation](/docs).
|
||||||
|
|
||||||
|
Before we take this template and build an image from it, let's validate the template
|
||||||
|
by running `packer validate example.json`. This command checks the syntax
|
||||||
|
as well as the configuration values to verify they look valid. The output should
|
||||||
|
look similar to below, because the template should be valid. If there are
|
||||||
|
any errors, this command will tell you.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ packer validate example.json
|
||||||
|
Template validated successfully.
|
||||||
|
```
|
||||||
|
|
||||||
|
Next, let's build the image from this template.
|
||||||
|
|
||||||
|
An astute reader may notice that we said earlier we'd be building an
|
||||||
|
image with Redis pre-installed, and yet the template we made doesn't reference
|
||||||
|
Redis anywhere. In fact, this part of the documentation will only cover making
|
||||||
|
a first basic, non-provisioned image. The next section on provisioning will
|
||||||
|
cover installing Redis.
|
||||||
|
|
||||||
|
## Your First Image
|
||||||
|
|
||||||
|
With a properly validated template. It is time to build your first image.
|
||||||
|
This is done by calling `packer build` with the template file. The output
|
||||||
|
should look similar to below. Note that this process typically takes a
|
||||||
|
few minutes.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ packer build example.json
|
||||||
|
==> amazon-ebs: amazon-ebs output will be in this color.
|
||||||
|
|
||||||
|
==> amazon-ebs: Creating temporary keypair for this instance...
|
||||||
|
==> amazon-ebs: Creating temporary security group for this instance...
|
||||||
|
==> amazon-ebs: Authorizing SSH access on the temporary security group...
|
||||||
|
==> amazon-ebs: Launching a source AWS instance...
|
||||||
|
==> amazon-ebs: Waiting for instance to become ready...
|
||||||
|
==> amazon-ebs: Connecting to the instance via SSH...
|
||||||
|
==> amazon-ebs: Stopping the source instance...
|
||||||
|
==> amazon-ebs: Waiting for the instance to stop...
|
||||||
|
==> amazon-ebs: Creating the AMI: packer-example 1371856345
|
||||||
|
==> amazon-ebs: AMI: ami-19601070
|
||||||
|
==> amazon-ebs: Waiting for AMI to become ready...
|
||||||
|
==> amazon-ebs: Terminating the source AWS instance...
|
||||||
|
==> amazon-ebs: Deleting temporary security group...
|
||||||
|
==> amazon-ebs: Deleting temporary keypair...
|
||||||
|
==> amazon-ebs: Build finished.
|
||||||
|
|
||||||
|
==> Builds finished. The artifacts of successful builds are:
|
||||||
|
--> amazon-ebs: AMIs were created:
|
||||||
|
|
||||||
|
us-east-1: ami-19601070
|
||||||
|
```
|
||||||
|
|
||||||
|
At the end of running `packer build`, Packer outputs the _artifacts_
|
||||||
|
that were created as part of the build. Artifacts are the results of a
|
||||||
|
build, and typically represent an ID (such as in the case of an AMI) or
|
||||||
|
a set of files (such as for a VMware virtual machine). In this example,
|
||||||
|
we only have a single artifact: the AMI in us-east-1 that was created.
|
||||||
|
|
||||||
|
This AMI is ready to use. If you wanted you can go and launch this AMI
|
||||||
|
right now and it would work great.
|
||||||
|
|
||||||
|
<div class="alert alert-block alert-info">
|
||||||
|
<strong>Note:</strong> Your AMI ID will surely be different than the
|
||||||
|
one above. If you try to launch the one in the example output above, you
|
||||||
|
will get an error. If you want to try to launch your AMI, get the ID from
|
||||||
|
the Packer output.
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## Managing the Image
|
||||||
|
|
||||||
|
Packer only builds images. It does not attempt to manage them in any way.
|
||||||
|
After they're built, it is up to you to launch or destroy them as you see
|
||||||
|
fit. As a result of this, after running the above example, your AWS account
|
||||||
|
now has an AMI associated with it.
|
||||||
|
|
||||||
|
AMIs are stored in S3 by Amazon, so unless you want to be charged about $0.01
|
||||||
|
per month, you'll probably want to remove it. Remove the AMI by
|
||||||
|
first deregistering it on the [AWS AMI management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Images).
|
||||||
|
Next, delete the associated snapshot on the
|
||||||
|
[AWS snapshot management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Snapshots).
|
||||||
|
|
||||||
|
Congratulations! You've just built your first image with Packer. Although
|
||||||
|
the image was pretty useless in this case (nothing was changed about it),
|
||||||
|
this page should've given you a general idea of how Packer works, what
|
||||||
|
templates are, and how to validate and build templates into machine
|
||||||
|
images.
|
||||||
|
|
@ -0,0 +1,93 @@
|
||||||
|
---
|
||||||
|
layout: "intro"
|
||||||
|
page_title: "Provision"
|
||||||
|
prev_url: "/intro/getting-started/build-image.html"
|
||||||
|
next_url: "/intro/getting-started/parallel-builds.html"
|
||||||
|
next_title: "Parallel Builds"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Provision
|
||||||
|
|
||||||
|
In the previous page of this guide, you created your first image with
|
||||||
|
Packer. The image you just built, however, was basically just a repackaging
|
||||||
|
of a previously existing base AMI. The real utility of Packer comes from
|
||||||
|
being able to install and configure software into the images as well.
|
||||||
|
This stage is also known as the _provision_ step. Packer fully supports
|
||||||
|
automated provisioning in order to install software onto the machines prior
|
||||||
|
to turning them into images.
|
||||||
|
|
||||||
|
In this section, we're going to complete our image by installing
|
||||||
|
Redis on it. This way, the image we end up building actually contains
|
||||||
|
Redis pre-installed. Although Redis is a small, simple example, this should
|
||||||
|
give you an idea of what it may be like to install many more packages into
|
||||||
|
the image.
|
||||||
|
|
||||||
|
Historically, pre-baked images have been frowned upon because changing
|
||||||
|
them has been so tedious and slow. Because Packer is completely automated,
|
||||||
|
including provisioning, images can be changed quickly and integrated with
|
||||||
|
modern configuration management tools such as Chef or Puppet.
|
||||||
|
|
||||||
|
## Configuring Provisioners
|
||||||
|
|
||||||
|
Provisioners are configured as part of the template. We'll use the built-in
|
||||||
|
shell provisioner that comes with Packer to install Redis. Modify the
|
||||||
|
`example.json` template we made previously and add the following. We'll
|
||||||
|
explain the various parts of the new configuration following the code
|
||||||
|
block below.
|
||||||
|
|
||||||
|
<pre class="prettyprint">
|
||||||
|
{
|
||||||
|
"builders": [...],
|
||||||
|
|
||||||
|
"provisioners": [{
|
||||||
|
"type": "shell",
|
||||||
|
"inline": [
|
||||||
|
"sudo apt-get update",
|
||||||
|
"sudo apt-get install -y redis-server"
|
||||||
|
]
|
||||||
|
}]
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
Hopefully it is obvious, but the `builders` section shouldn't actually
|
||||||
|
contain "...", it should be the contents setup in the previous page
|
||||||
|
of the getting started guide.
|
||||||
|
|
||||||
|
To configure the provisioners, we add a new section `provisioners` to the
|
||||||
|
template, alongside the `builders` configuration. The provisioners section
|
||||||
|
is an array of provisioners to run. If multiple provisioners are specified, they
|
||||||
|
are run in the order given.
|
||||||
|
|
||||||
|
By default, each provisioner is run for every builder defined. So if we had
|
||||||
|
two builders defined in our template, such as both Amazon and DigitalOcean, then
|
||||||
|
the shell script would run as part of both builds. There are ways to restrict
|
||||||
|
provisioners to certain builds, but it is outside the scope of this getting
|
||||||
|
started guide. It is covered in more detail in the complete
|
||||||
|
[documentation](/docs).
|
||||||
|
|
||||||
|
The one provisioner we defined has a type of `shell`. This provisioner
|
||||||
|
ships with Packer and runs shell scripts on the running machine. In our
|
||||||
|
case, we specify two inline commands to run in order to install Redis.
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
With the provisioner configured, give it a pass once again through
|
||||||
|
`packer validate` to verify everything is okay, then build it using
|
||||||
|
`packer build example.json`. The output should look similar to when you
|
||||||
|
built your first image, except this time there will be a new step where
|
||||||
|
the provisoning is run.
|
||||||
|
|
||||||
|
The output from the provisioner is too verbose to include in this
|
||||||
|
guide, since it contains all the output from the shell scripts. But you
|
||||||
|
should see Redis successfully install. After that, Packer once again
|
||||||
|
turns the machine into an AMI.
|
||||||
|
|
||||||
|
If you were to launch this AMI, Redis would be pre-installed. Cool!
|
||||||
|
|
||||||
|
This is just a basic example. In a real world use case, you may be provisioning
|
||||||
|
an image with the entire stack necessary to run your application. Or maybe
|
||||||
|
just the web stack so that you can have an image for web servers pre-built.
|
||||||
|
This saves tons of time later as you launch these images since everything
|
||||||
|
is pre-installed. Additionally, since everything is pre-installed, you
|
||||||
|
can test the images as they're built and know that when they go into
|
||||||
|
production, they'll be functional.
|
||||||
|
|
@ -13,8 +13,8 @@
|
||||||
<ul>
|
<ul>
|
||||||
<li><h4>Getting Started</h4></li>
|
<li><h4>Getting Started</h4></li>
|
||||||
<li><a href="/intro/getting-started/setup.html">Install Packer</a></li>
|
<li><a href="/intro/getting-started/setup.html">Install Packer</a></li>
|
||||||
<li><a href="#">Build an Image</a></li>
|
<li><a href="/intro/getting-started/build-image.html">Build an Image</a></li>
|
||||||
<li><a href="#">Provision</a></li>
|
<li><a href="/intro/getting-started/provision.html">Provision</a></li>
|
||||||
<li><a href="#">Parallel Builds</a></li>
|
<li><a href="#">Parallel Builds</a></li>
|
||||||
<li><a href="#">Post-Process</a></li>
|
<li><a href="#">Post-Process</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
|
||||||
|
|
@ -142,11 +142,15 @@
|
||||||
padding: $docs-top-margin 80px;
|
padding: $docs-top-margin 80px;
|
||||||
display: block;
|
display: block;
|
||||||
|
|
||||||
|
p code {
|
||||||
|
font-size: 14px;
|
||||||
|
}
|
||||||
|
|
||||||
code {
|
code {
|
||||||
background-color: #000;
|
background-color: #000;
|
||||||
border: 0;
|
border: 0;
|
||||||
color: #b1d631;
|
color: #b1d631;
|
||||||
font-size: 14px;
|
font-size: 12px;
|
||||||
}
|
}
|
||||||
|
|
||||||
a {
|
a {
|
||||||
|
|
@ -193,7 +197,7 @@
|
||||||
|
|
||||||
pre {
|
pre {
|
||||||
border: 0;
|
border: 0;
|
||||||
font-size: 14px;
|
font-size: 12px;
|
||||||
margin-left: -80px;
|
margin-left: -80px;
|
||||||
margin-right: -80px;
|
margin-right: -80px;
|
||||||
padding-top: 40px;
|
padding-top: 40px;
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue