From 439cfb4ded053cfb92b9d317fab1add3048dde58 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 27 Jun 2013 08:17:00 -0700 Subject: [PATCH] website: document the vagrant post-processor --- website/config.rb | 38 +++--- .../post-processors/vagrant.html.markdown | 110 ++++++++++++++++++ website/source/layouts/docs.erb | 5 + 3 files changed, 136 insertions(+), 17 deletions(-) create mode 100644 website/source/docs/post-processors/vagrant.html.markdown diff --git a/website/config.rb b/website/config.rb index 4dac11e29..704db960f 100644 --- a/website/config.rb +++ b/website/config.rb @@ -7,27 +7,31 @@ raise "PACKER_VERSION must be set." if !ENV["PACKER_VERSION"] # Download the list of Packer downloads #------------------------------------------------------------------------- -http = Net::HTTP.new("dl.bintray.com", 80) -req = Net::HTTP::Get.new("/mitchellh/packer") -req.basic_auth "mitchellh", ENV["BINTRAY_API_KEY"] -response = http.request(req) - $packer_files = {} -response.body.split("\n").each do |line| - next if line !~ /\/mitchellh\/packer\/(#{ENV["PACKER_VERSION"]}.+?)\?/ - filename = $1.to_s - os = filename.split("_")[1] +$packer_os = [] - $packer_files[os] ||= [] - $packer_files[os] << filename -end +if !ENV["PACKER_DISABLE_DOWNLOAD_FETCH"] + http = Net::HTTP.new("dl.bintray.com", 80) + req = Net::HTTP::Get.new("/mitchellh/packer") + req.basic_auth "mitchellh", ENV["BINTRAY_API_KEY"] + response = http.request(req) -$packer_os = ["darwin", "linux", "windows"] & $packer_files.keys -$packer_os += $packer_files.keys -$packer_os.uniq! + response.body.split("\n").each do |line| + next if line !~ /\/mitchellh\/packer\/(#{ENV["PACKER_VERSION"]}.+?)\?/ + filename = $1.to_s + os = filename.split("_")[1] -$packer_files.each do |key, value| - value.sort! + $packer_files[os] ||= [] + $packer_files[os] << filename + end + + $packer_os = ["darwin", "linux", "windows"] & $packer_files.keys + $packer_os += $packer_files.keys + $packer_os.uniq! + + $packer_files.each do |key, value| + value.sort! + end end #------------------------------------------------------------------------- diff --git a/website/source/docs/post-processors/vagrant.html.markdown b/website/source/docs/post-processors/vagrant.html.markdown new file mode 100644 index 000000000..d22a4951c --- /dev/null +++ b/website/source/docs/post-processors/vagrant.html.markdown @@ -0,0 +1,110 @@ +--- +layout: "docs" +page_title: "Vagrant Post-Processor" +--- + +# Vagrant Post-Processor + +Type: `vagrant` + +The Vagrant post-processor takes a build and converts the artifact +into a valid [Vagrant](http://www.vagrantup.com) box, if it can. +This lets you use Packer to automatically create arbitrarily complex +Vagrant boxes, and is in fact how the official boxes distributed by +Vagrant are created. + +If you've never used a post-processor before, please read the +documentation on [using post-processors](/docs/templates/post-processors.html) +in templates. This knowledge will be expected for the remainder of +this document. + +Because Vagrant boxes are [provider-specific](#), +the Vagrant post-processor is hardcoded to understand how to convert +the artifacts of certain builders into proper boxes for their +respective providers. + +Currently, the Vagrant post-processor can create boxes for the following +providers. + +* AWS +* VirtualBox +* VMware + +
+Support for additional providers is planned. If the +Vagrant post-processor doesn't support creating boxes for a provider you +care about, please help by contributing to Packer and adding support for it. +
+ +## Configuration + +The simplest way to use the post-processor is to just enable it. No +configuration is required by default. This will mostly do what you expect +and will build functioning boxes for many of the built-in builders of +Packer. + +However, if you want to configure things a bit more, the post-processor +does expose some configuration options. The available options are listed +below, with more details about certain options in following sections. + +* `output` (string) - The full path to the box file that will be created + by this post-processor. This is a + [configuration template](/docs/templates/configuration-templates.html). + The variable `Provider` is replaced by the Vagrant provider the box is for. + By default, the value of this config is `packer_{{.Provider}}.box`. + +* `aws`, `virtualbox`, or `vmware` (objects) - These are used to configure + the specific options for certain providers. A reference of available + configuration parameters for each is in the section below. + +### AWS Provider + +The AWS provider itself can be configured with specific options: + +* `vagrantfile_template` (string) - Path to a template to use for the + Vagrantfile that is packaged with the box. The contents of the file must be a valid Go + [text template](http://golang.org/pkg/text/template). By default + this is a template that simply sets the AMIs for the various regions + of the AWS build. + +The `vagrantfile_template` has the `Images` variable which is a map +of region (string) to AMI ID (string). An example Vagrantfile template for +AWS is shown below. The example simply sets the AMI for each region. + +``` +Vagrant.configure("2") do |config| + config.vm.provider "aws" do |aws| + {{ range $region, $ami := .Images }} + aws.region_config "{{ $region }}", ami: "{{ $ami }}" + {{ end }} + end +end +``` + +### VirtualBox Provider + +The VirtualBox provider itself can be configured with specific options: + +* `vagrantfile_template` (string) - Path to a template to use for the + Vagrantfile that is packaged with the box. The contents of the file must be a valid Go + [text template](http://golang.org/pkg/text/template). By default this is + a template that just sets the base MAC address so that networking works. + +The `vagrantfile_template` has the `BaseMACAddress` variable which is a string +containing the MAC address of the first network interface. This must be set +in the Vagrantfile for networking to work properly with Vagrant. An example +Vagrantfile template is shown below: + +``` +TODO +``` + +### VMware Provider + +The VMware provider itself can be configured with specific options: + +* `vagrantfile_template` (string) - Path to a template to use for the + Vagrantfile that is packaged with the box. The contents of the file must be a valid Go + [text template](http://golang.org/pkg/text/template). By default no + Vagrantfile is packaged with the box. Note that currently no variables + are available in the template, but this may change in the future. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 0124d5a6d..c00993869 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -38,6 +38,11 @@
  • Custom
    • + +