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