diff --git a/website/source/docs/builders/amazon-ebs.html.markdown b/website/source/docs/builders/amazon-ebs.html.markdown index e04e7615b..3d067bf8c 100644 --- a/website/source/docs/builders/amazon-ebs.html.markdown +++ b/website/source/docs/builders/amazon-ebs.html.markdown @@ -1,22 +1,17 @@ --- layout: "docs" +page_title: "Amazon AMI Builder (EBS backed)" --- -# Amazon AMI Builder +# AMI Builder (EBS backed) Type: `amazon-ebs` The `amazon-ebs` builder is able to create Amazon AMIs backed by EBS -volumes for use in [EC2](http://aws.amazon.com/ec2/). The builder takes -an initial source AMI, runs any provisioning necesary on the instance, -and snapshots it into a reusable AMI. - -Amazon supports two types of AMIs: EBS-backed and instance-store. Instance -store AMIs are considerably harder to create, requiring many platform-specific -steps that can often take a very long time. EBS-backed AMIs, on the hand, -only require a source AMI to exist. This builder only builds EBS-backed -instances, because they are easier to create, especially across many -platforms running Packer. +volumes for use in [EC2](http://aws.amazon.com/ec2/). For more information +on the difference betwen EBS-backed instances and instance-store backed +instances, see the +["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). This builder builds an AMI by launching an EC2 instance from a source AMI, provisioning that running machine, and then creating an AMI from that machine. diff --git a/website/source/docs/builders/amazon-instance.html.markdown b/website/source/docs/builders/amazon-instance.html.markdown new file mode 100644 index 000000000..8f685136c --- /dev/null +++ b/website/source/docs/builders/amazon-instance.html.markdown @@ -0,0 +1,217 @@ +--- +layout: "docs" +page_title: "Amazon AMI Builder (instance-store)" +--- + +# AMI Builder (instance-store) + +Type: `amazon-instance` + +The `amazon-instance` builder is able to create Amazon AMIs backed by +instance storage as the root device. For more information on the difference +between instance storage and EBS-backed instances, see the +["storage for the root device" section in the EC2 documentation](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ComponentsAMIs.html#storage-for-the-root-device). + +This builder builds an AMI by launching an EC2 instance from an existing +instance-storage backed AMI, provisioning that running machine, and then +bundling and creating a new AMI from that machine. +This is all done in your own AWS account. The builder will create temporary +keypairs, security group rules, etc. that provide it temporary access to +the instance while the image is being created. This simplifies configuration +quite a bit. + +The builder does _not_ manage AMIs. Once it creates an AMI and stores it +in your account, it is up to you to use, delete, etc. the AMI. + +## Configuration Reference + +There are many configuration options available for the builder. They are +segmented below into two categories: required and optional parameters. Within +each category, the available configuration keys are alphabetized. + +Required: + +* `access_key` (string) - The access key used to communicate with AWS. + If not specified, Packer will attempt to read this from environmental + variables `AWS_ACCESS_KEY_ID` or `AWS_ACCESS_KEY` (in that order). + +* `account_id` (string) - Your AWS account ID. This is required for bundling + the AMI. This is _not the same_ as the access key. You can find your + account ID in the security credentials page of your AWS account. + +* `ami_name` (string) - The name of the resulting AMI that will appear + when managing AMIs in the AWS console or via APIs. This must be unique. + To help make this unique, certain template parameters are available for + this value, which are documented below. + +* `instance_type` (string) - The EC2 instance type to use while building + the AMI, such as "m1.small". + +* `region` (string) - The name of the region, such as "us-east-1", in which + to launch the EC2 instance to create the AMI. + +* `s3_bucket` (string) - The name of the S3 bucket to upload the AMI. + This bucket will be created if it doesn't exist. + +* `secret_key` (string) - The secret key used to communicate with AWS. + If not specified, Packer will attempt to read this from environmental + variables `AWS_SECRET_ACCESS_KEY` or `AWS_SECRET_KEY` (in that order). + +* `source_ami` (string) - The initial AMI used as a base for the newly + created machine. + +* `ssh_username` (string) - The username to use in order to communicate + over SSH to the running machine. + +* `x509_cert_path` (string) - The local path to a valid X509 certificate for + your AWS account. This is used for bundling the AMI. This X509 certificate + must be registered with your account from the security credentials page + in the AWS console. + +* `x509_key_path` (string) - The local path to the private key for the X509 + certificate specified by `x509_cert_path`. This is used for bundling the AMI. + +Optional: + +* `bundle_destination` (string) - The directory on the running instance + where the bundled AMI will be saved prior to uploading. By default this is + "/tmp". This directory must exist and be writable. + +* `bundle_prefix` (string) - The prefix for files created from bundling + the root volume. By default this is "image-{{.Createtime}}". The `CreateTime` + variable should be used to make sure this is unique, otherwise it can + collide with other created AMIs by Packer in your account. + +* `bundle_upload_command` (string) - The command to use to upload the + bundled volume. See the "custom bundle commands" section below for more + information. + +* `bundle_vol_command` (string) - The command to use to bundle the volume. + See the "custom bundle commands" section below for more information. + +* `security_group_id` (string) - The ID (_not_ the name) of the security + group to assign to the instance. By default this is not set and Packer + will automatically create a new temporary security group to allow SSH + access. Note that if this is specified, you must be sure the security + group allows access to the `ssh_port` given below. + +* `ssh_port` (int) - The port that SSH will be available on. This defaults + to port 22. + +* `ssh_timeout` (string) - The time to wait for SSH to become available + before timing out. The format of this value is a duration such as "5s" + or "5m". The default SSH timeout is "1m", or one minute. + +* `subnet_id` (string) - If using VPC, the ID of the subnet, such as + "subnet-12345def", where Packer will launch the EC2 instance. + +* `vpc_id` (string) - If launching into a VPC subnet, Packer needs the + VPC ID in order to create a temporary security group within the VPC. + +* `x509_upload_path` (string) - The path on the remote machine where the + X509 certificate will be uploaded. This path must already exist and be + writable. X509 certificates are uploaded after provisioning is run, so + it is perfectly okay to create this directory as part of the provisioning + process. + +## Basic Example + +Here is a basic example. It is completely valid except for the access keys: + +
+{ + "type": "amazon-instance", + "access_key": "YOUR KEY HERE", + "secret_key": "YOUR SECRET KEY HERE", + "region": "us-east-1", + "source_ami": "ami-d9d6a6b0", + "instance_type": "m1.small", + "ssh_username": "ubuntu", + + "account_id": "0123-4567-0890", + "s3_bucket": "packer-images", + "x509_cert_path": "x509.cert", + "x509_key_path": "x509.key", + "x509_upload_path": "/tmp", + + "ami_name": "packer-quick-start {{.CreateTime}}" +} ++ +