diff --git a/website/source/assets/images/packer-signed-urls.png b/website/source/assets/images/packer-signed-urls.png new file mode 100644 index 000000000..4e9e17010 Binary files /dev/null and b/website/source/assets/images/packer-signed-urls.png differ diff --git a/website/source/docs/command-line/push.html.markdown b/website/source/docs/command-line/push.html.markdown index 764333967..57ea58cf0 100644 --- a/website/source/docs/command-line/push.html.markdown +++ b/website/source/docs/command-line/push.html.markdown @@ -1,28 +1,36 @@ --- description: | - The `packer push` Packer command takes a template and pushes it to a build - service that will automatically build this Packer template. + The `packer push` command uploads a template and other required files to the + Atlas build service, which will run your packer build for you. layout: docs page_title: 'Push - Command-Line' ... # Command-Line: Push -The `packer push` Packer command takes a template and pushes it to a Packer -build service such as [HashiCorp's Atlas](https://atlas.hashicorp.com). The -build service will automatically build your Packer template and expose the -artifacts. +The `packer push` command uploads a template and other required files to the +Atlas service, which will run your packer build for you. [Learn more about +Packer in Atlas.](https://atlas.hashicorp.com/help/packer/features) -External build services such as HashiCorp's Atlas make it easy to iterate on -Packer templates, especially when the builder you are running may not be easily -accessable (such as developing `qemu` builders on Mac or Windows). +Running builds remotely makes it easier to iterate on packer builds that are not +supported on your operating system, for example, building docker or QEMU while +developing on Mac or Windows. Also, the hard work of building VMs is offloaded +to dedicated servers with more CPU, memory, and network resources. -!> The Packer build service will receive the raw copy of your Packer template -when you push. **If you have sensitive data in your Packer template, you should -move that data into Packer variables or environment variables!** +When you use push to run a build in Atlas, you may also want to store your build +artifacts in Atlas. In order to do that you will also need to configure the +[Atlas post-processor](/docs/post-processors/atlas.html). This is optional, and +both the post-processor and push commands can be used independently. -For the `push` command to work, the [push -configuration](/docs/templates/push.html) must be completed within the template. +!> The push command uploads your template and other files, like provisioning +scripts, to Atlas. Take care not to upload files that you don't intend to, like +secrets or large binaries. **If you have secrets in your Packer template, you +should [move them into environment +variables](https://packer.io/docs/templates/user-variables.html).** + +Most push behavior is [configured in your packer +template](/docs/templates/push.html). You can override or supplement your +configuration using the options below. ## Options @@ -30,12 +38,21 @@ configuration](/docs/templates/push.html) must be completed within the template. template much like a VCS commit message. This message will be passed to the Packer build service. This option is also available as a short option `-m`. -- `-token` - An access token for authenticating the push to the Packer build - service such as Atlas. This can also be specified within the push - configuration in the template. +- `-token` - Your access token for the Atlas API. + +-> Login to Atlas to [generate an Atlas +Token](https://atlas.hashicorp.com/settings/tokens). The most convenient way to +configure your token is to set it to the `ATLAS_TOKEN` environment variable, but +you can also use `-token` on the command line. - `-name` - The name of the build in the service. This typically looks like - `hashicorp/precise64`. + `hashicorp/precise64`, which follows the form `/`. This + must be specified here or in your template. + +- `-var` - Set a variable in your packer template. This option can be used + multiple times. This is useful for setting version numbers for your build. + +- `-var-file` - Set template variables from a file. ## Examples @@ -50,3 +67,32 @@ Push a Packer template with a custom token: ``` {.shell} $ packer push -token ABCD1234 template.json ``` + +## Limits + +`push` is limited to 5gb upload when pushing to Atlas. To be clear, packer *can* +build artifacts larger than 5gb, and Atlas *can* store artifacts larger than +5gb. However, the initial payload you push to *start* the build cannot exceed +5gb. If your boot ISO is larger than 5gb (for example if you are building OSX +images), you will need to put your boot ISO in an external web service and +download it during the packer run. + +## Building Private `.iso` and `.dmg` Files + +If you want to build a private `.iso` file you can upload the `.iso` to a secure +file hosting service like [Amazon +S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURL.html), +[Google Cloud +Storage](https://cloud.google.com/storage/docs/gsutil/commands/signurl), or +[Azure File +Service](https://msdn.microsoft.com/en-us/library/azure/dn194274.aspx) and +download it at build time using a signed URL. You should convert `.dmg` files to +`.iso` and follow a similar procedure. + +Once you have added [variables in your packer +template](/docs/templates/user-variables.html) you can specify credentials or +signed URLs using Atlas environment variables, or via the `-var` flag when you +run `push`. + +![Configure your signed URL in the Atlas build variables +menu](/assets/images/packer-signed-urls.png) diff --git a/website/source/docs/post-processors/atlas.html.markdown b/website/source/docs/post-processors/atlas.html.markdown index 4f2cb3640..435bec7c4 100644 --- a/website/source/docs/post-processors/atlas.html.markdown +++ b/website/source/docs/post-processors/atlas.html.markdown @@ -11,9 +11,15 @@ page_title: 'Atlas Post-Processor' Type: `atlas` -The Atlas post-processor for Packer receives an artifact from a Packer build and -uploads it to Atlas. [Atlas](https://atlas.hashicorp.com) hosts and serves -artifacts, allowing you to version and distribute them in a simple way. +The Atlas post-processor uploads artifacts from your packer builds to Atlas for +hosting. Artifacts hosted in Atlas are are automatically made available for use +with Vagrant and Terraform, and Atlas provides additional features for managing +versions and releases. [Learn more about packer in +Atlas.](https://atlas.hashicorp.com/help/packer/features) + +You can also use the push command to [run packer builds in +Atlas](/docs/command-line/push.html). The push command and Atlas post-processor +can be used together or independently. ## Workflow @@ -40,24 +46,22 @@ The configuration allows you to specify and access the artifact in Atlas. ### Required: -- `token` (string) - Your access token for the Atlas API. This can be - generated on your [tokens - page](https://atlas.hashicorp.com/settings/tokens). Alternatively you can - export your Atlas token as an environmental variable and remove it from - the configuration. +- `token` (string) - Your access token for the Atlas API. + +-> Login to Atlas to [generate an Atlas +Token](https://atlas.hashicorp.com/settings/tokens). The most convenient way to +configure your token is to set it to the `ATLAS_TOKEN` environment variable, but +you can also use `token` configuration option. - `artifact` (string) - The shorthand tag for your artifact that maps to Atlas, i.e `hashicorp/foobar` for `atlas.hashicorp.com/hashicorp/foobar`. - You must have access to the organization, hashicorp in this example, in - order to add an artifact to the organization in Atlas. + You must have access to the organization—hashicorp in this example—in order + to add an artifact to the organization in Atlas. - `artifact_type` (string) - For uploading AMIs to Atlas, `artifact_type` will always be `amazon.ami`. This field must be defined because Atlas can host other artifact types, such as Vagrant boxes. --> **Note:** If you want to upload Vagrant boxes to Atlas, use the [Atlas -post-processor](/docs/post-processors/atlas.html). - ### Optional: - `atlas_url` (string) - Override the base URL for Atlas. This is useful if