diff --git a/website/source/intro/getting-started/build-image.html.markdown b/website/source/intro/getting-started/build-image.html.markdown new file mode 100644 index 000000000..7f15f2977 --- /dev/null +++ b/website/source/intro/getting-started/build-image.html.markdown @@ -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. + +
+Note that if you're not using an account that qualifies under +the AWS free-tier, 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. +
+ +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: + +
+{
+  "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}}"
+  }]
+}
+
+ +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. + +
+Note: 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. +
+ +## 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. diff --git a/website/source/intro/getting-started/provision.html.markdown b/website/source/intro/getting-started/provision.html.markdown new file mode 100644 index 000000000..703e466ee --- /dev/null +++ b/website/source/intro/getting-started/provision.html.markdown @@ -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. + +
+{
+  "builders": [...],
+
+  "provisioners": [{
+    "type": "shell",
+    "inline": [
+      "sudo apt-get update",
+      "sudo apt-get install -y redis-server"
+    ]
+  }]
+}
+
+ +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. diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 8865deedf..e1c82c88e 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -13,8 +13,8 @@ diff --git a/website/source/stylesheets/_components.scss b/website/source/stylesheets/_components.scss index d298c83df..1dbcc43cc 100644 --- a/website/source/stylesheets/_components.scss +++ b/website/source/stylesheets/_components.scss @@ -142,11 +142,15 @@ padding: $docs-top-margin 80px; display: block; + p code { + font-size: 14px; + } + code { background-color: #000; border: 0; color: #b1d631; - font-size: 14px; + font-size: 12px; } a { @@ -193,7 +197,7 @@ pre { border: 0; - font-size: 14px; + font-size: 12px; margin-left: -80px; margin-right: -80px; padding-top: 40px;