github.com/phobos182/packer@v0.2.3-0.20130819023704-c84d2aeffc68/website/source/intro/getting-started/build-image.html.markdown (about) 1 --- 2 layout: "intro" 3 page_title: "Build an Image" 4 prev_url: "/intro/getting-started/setup.html" 5 next_url: "/intro/getting-started/provision.html" 6 next_title: "Provision" 7 --- 8 9 # Build an Image 10 11 With Packer installed, let's just dive right into it and build our first 12 image. Our first image will be an [Amazon EC2 AMI](http://aws.amazon.com/ec2/) 13 with Redis pre-installed. This is just an example. Packer can create images 14 for [many platforms](/intro/platforms.html) with anything pre-installed. 15 16 If you don't have an AWS account, [create one now](http://aws.amazon.com/free/). 17 For the example, we'll use a "t1.micro" instance to build our image, which 18 qualifies under the AWS [free-tier](http://aws.amazon.com/free/), meaning 19 it will be free. If you already have an AWS account, you may be charged some 20 amount of money, but it shouldn't be more than a few cents. 21 22 <div class="alert alert-block alert-warn"> 23 <strong>Note</strong> that if you're not using an account that qualifies under 24 the AWS <a href="http://aws.amazon.com/free/">free-tier</a>, you may be 25 charged to run these examples. The charge should only be a few cents, but 26 we're not responsible if it ends up being more. 27 </div> 28 29 Packer can build images for [many platforms](/intro/platforms.html) other than 30 AWS, but AWS requires no additional software installed on your computer and 31 their [free-tier](http://aws.amazon.com/free/) makes it free to use for most 32 people. This is why we chose to use AWS for the example. If you're uncomfortable 33 setting up an AWS account, feel free to follow along as the basic principles 34 apply to the other platforms as well. 35 36 ## The Template 37 38 The configuration file used to define what image we want built and how 39 is called a _template_ in Packer terminology. The format of a template 40 is simple [JSON](http://www.json.org/). JSON struck the best balance between 41 human-editable and machine-editable, allowing both hand-made templates as well 42 as machine generated templates to easily be made. 43 44 We'll start by creating the entire template, then we'll go over each section 45 briefly. Create a file `example.json` and fill it with the following contents: 46 47 <pre class="prettyprint"> 48 { 49 "builders": [{ 50 "type": "amazon-ebs", 51 "access_key": "YOUR KEY HERE", 52 "secret_key": "YOUR SECRET KEY HERE", 53 "region": "us-east-1", 54 "source_ami": "ami-de0d9eb7", 55 "instance_type": "t1.micro", 56 "ssh_username": "ubuntu", 57 "ami_name": "packer-example {{timestamp}}" 58 }] 59 } 60 </pre> 61 62 Please fill in the `access_key` and `secret_key` with the proper values 63 for your account. Your security credentials can be found on 64 [this page](https://console.aws.amazon.com/iam/home?#security_credential). 65 66 This is a basic template that is ready-to-go. It should be immediately recognizable 67 as a normal, basic JSON object. Within the object, the `builders` section 68 contains an array of JSON objects configuring a specific _builder_. A 69 builder is a component of Packer that is responsible for creating a machine 70 and turning that machine into an image. 71 72 In this case, we're only configuring a single builder of type `amazon-ebs`. 73 This is the Amazon EC2 AMI builder that ships with Packer. This builder 74 builds an EBS-backed AMI by launching a source AMI, provisioning on top of 75 that, and re-packaging it into a new AMI. 76 77 The additional keys within the object are configuration for this builder, specifying things 78 such as access keys, the source AMI to build from, and more. 79 The exact set of configuration variables available for a builder are 80 specific to each builder and can be found within the [documentation](/docs). 81 82 Before we take this template and build an image from it, let's validate the template 83 by running `packer validate example.json`. This command checks the syntax 84 as well as the configuration values to verify they look valid. The output should 85 look similar to below, because the template should be valid. If there are 86 any errors, this command will tell you. 87 88 ``` 89 $ packer validate example.json 90 Template validated successfully. 91 ``` 92 93 Next, let's build the image from this template. 94 95 An astute reader may notice that we said earlier we'd be building an 96 image with Redis pre-installed, and yet the template we made doesn't reference 97 Redis anywhere. In fact, this part of the documentation will only cover making 98 a first basic, non-provisioned image. The next section on provisioning will 99 cover installing Redis. 100 101 ## Your First Image 102 103 With a properly validated template. It is time to build your first image. 104 This is done by calling `packer build` with the template file. The output 105 should look similar to below. Note that this process typically takes a 106 few minutes. 107 108 ``` 109 $ packer build example.json 110 ==> amazon-ebs: amazon-ebs output will be in this color. 111 112 ==> amazon-ebs: Creating temporary keypair for this instance... 113 ==> amazon-ebs: Creating temporary security group for this instance... 114 ==> amazon-ebs: Authorizing SSH access on the temporary security group... 115 ==> amazon-ebs: Launching a source AWS instance... 116 ==> amazon-ebs: Waiting for instance to become ready... 117 ==> amazon-ebs: Connecting to the instance via SSH... 118 ==> amazon-ebs: Stopping the source instance... 119 ==> amazon-ebs: Waiting for the instance to stop... 120 ==> amazon-ebs: Creating the AMI: packer-example 1371856345 121 ==> amazon-ebs: AMI: ami-19601070 122 ==> amazon-ebs: Waiting for AMI to become ready... 123 ==> amazon-ebs: Terminating the source AWS instance... 124 ==> amazon-ebs: Deleting temporary security group... 125 ==> amazon-ebs: Deleting temporary keypair... 126 ==> amazon-ebs: Build finished. 127 128 ==> Builds finished. The artifacts of successful builds are: 129 --> amazon-ebs: AMIs were created: 130 131 us-east-1: ami-19601070 132 ``` 133 134 At the end of running `packer build`, Packer outputs the _artifacts_ 135 that were created as part of the build. Artifacts are the results of a 136 build, and typically represent an ID (such as in the case of an AMI) or 137 a set of files (such as for a VMware virtual machine). In this example, 138 we only have a single artifact: the AMI in us-east-1 that was created. 139 140 This AMI is ready to use. If you wanted you can go and launch this AMI 141 right now and it would work great. 142 143 <div class="alert alert-block alert-info"> 144 <strong>Note:</strong> Your AMI ID will surely be different than the 145 one above. If you try to launch the one in the example output above, you 146 will get an error. If you want to try to launch your AMI, get the ID from 147 the Packer output. 148 </div> 149 150 ## Managing the Image 151 152 Packer only builds images. It does not attempt to manage them in any way. 153 After they're built, it is up to you to launch or destroy them as you see 154 fit. As a result of this, after running the above example, your AWS account 155 now has an AMI associated with it. 156 157 AMIs are stored in S3 by Amazon, so unless you want to be charged about $0.01 158 per month, you'll probably want to remove it. Remove the AMI by 159 first deregistering it on the [AWS AMI management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Images). 160 Next, delete the associated snapshot on the 161 [AWS snapshot management page](https://console.aws.amazon.com/ec2/home?region=us-east-1#s=Snapshots). 162 163 Congratulations! You've just built your first image with Packer. Although 164 the image was pretty useless in this case (nothing was changed about it), 165 this page should've given you a general idea of how Packer works, what 166 templates are, and how to validate and build templates into machine 167 images.