resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update packer sections

This commit is contained in:
Seth Vargo 2017-04-07 00:00:42 -04:00
parent 1bd0e49f2b
commit 1e35245a49
No known key found for this signature in database
GPG Key ID: C921994F9C27E0FF
13 changed files with 298 additions and 257 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
website/source/docs/enterprise/packer/artifacts/creating-amis.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Creating AMI Artifacts"
page_title: "Creating AMIs - Packer Artifacts - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerartifacts-amis"
description: |-
Creating AMI artifacts with Terraform Enterprise.
@ -8,53 +8,58 @@ description: |-
# Creating AMI Artifacts with Terraform Enterprise
In an immutable infrastructure workflow, it's important to version and store full images (artifacts)
to be deployed. This section covers storing [AWS AMI](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html)
images in Terraform Enterprise to be queried and used later.
In an immutable infrastructure workflow, it's important to version and store
full images (artifacts) to be deployed. This section covers storing [AWS
AMI](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) images in
Terraform Enterprise to be queried and used later.
Note the actual AMI does _not get stored_. Terraform Enterprise
simply keeps the AMI ID as a reference to the target image. Tools
like Terraform can then use this in a deploy.
Note the actual AMI does _not get stored_. Terraform Enterprise simply keeps the
AMI ID as a reference to the target image. Tools like Terraform can then use
this in a deploy.
### Steps
If you run Packer in Terraform Enterprise, the following will happen after a [push](/docs/enterprise/packer/builds/starting.html):
1. Terraform Enterprise will run `packer build` against your template in our infrastructure.
This spins up an AWS instance in your account and provisions it with
any specified provisioners
2. Packer stops the instance and stores the result as an AMI in AWS
under your account. This then returns an ID (the artifact) that it passes to the post-processor
3. The post-processor creates and uploads the new artifact version with the
ID in Terraform Enterprise of the type `amazon.image` for use later
1. Terraform Enterprise will run `packer build` against your template in our
infrastructure. This spins up an AWS instance in your account and provisions it
with any specified provisioners
2. Packer stops the instance and stores the result as an AMI in AWS under your
account. This then returns an ID (the artifact) that it passes to the
post-processor
3. The post-processor creates and uploads the new artifact version with the ID
in Terraform Enterprise of the type `amazon.image` for use later
### Example
Below is a complete example Packer template that starts an AWS instance.
```json
{
"push": {
"name": "my-username/frontend"
},
"provisioners": [],
"builders": [
{
"push": {
"name": "%{DEFAULT_USERNAME}/frontend"
},
"provisioners": [],
"builders": [
{
"type": "amazon-ebs",
"access_key": "",
"secret_key": "",
"region": "us-east-1",
"source_ami": "ami-2ccc7a44",
"instance_type": "c3.large",
"ssh_username": "ubuntu",
"ami_name": "TFE Example {{ timestamp }}"
}
],
"post-processors": [
{
"type": "atlas",
"artifact": "%{DEFAULT_USERNAME}/web-server",
"artifact_type": "amazon.image"
}
]
"type": "amazon-ebs",
"access_key": "",
"secret_key": "",
"region": "us-east-1",
"source_ami": "ami-2ccc7a44",
"instance_type": "c3.large",
"ssh_username": "ubuntu",
"ami_name": "TFE Example {{ timestamp }}"
}
],
"post-processors": [
{
"type": "atlas",
"artifact": "my-username/web-server",
"artifact_type": "amazon.image"
}
]
}
```

133
website/source/docs/enterprise/packer/artifacts/creating-vagrant-boxes.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Creating Vagrant Artifacts"
page_title: "Creating Vagrant Boxes - Packer Artifacts - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerartifacts-vagrant"
description: |-
Creating Vagrant artifacts with Terraform Enterprise.
@ -8,37 +8,42 @@ description: |-
# Creating Vagrant Boxes with Packer
We recommend using Packer to create boxes, as is it is fully repeatable and keeps a strong
history of changes within Terraform Enterprise.
We recommend using Packer to create boxes, as is it is fully repeatable and
keeps a strong history of changes within Terraform Enterprise.
## Getting Started
Using Packer requires more up front effort, but the repeatable and
automated builds will end any manual management of boxes. Additionally,
all boxes will be stored and served from Terraform Enterprise, keeping a history along
the way.
Using Packer requires more up front effort, but the repeatable and automated
builds will end any manual management of boxes. Additionally, all boxes will be
stored and served from Terraform Enterprise, keeping a history along the way.
## Post-Processors
Packer uses [post-processors](https://packer.io/docs/templates/post-processors.html) to define how to process
images and artifacts after provisioning. Both the `vagrant` and `atlas` post-processors must be used in order
to upload Vagrant Boxes to Terraform Enterprise via Packer.
Packer uses
[post-processors](https://packer.io/docs/templates/post-processors.html) to
define how to process images and artifacts after provisioning. Both the
`vagrant` and `atlas` post-processors must be used in order to upload Vagrant
Boxes to Terraform Enterprise via Packer.
It's important that they are [sequenced](https://packer.io/docs/templates/post-processors.html)
in the Packer template so they run in order. This is done by nesting arrays:
"post-processors": [
[
{
"type": "vagrant"
...
},
{
"type": "atlas"
...
}
]
```javascript
{
"post-processors": [
[
{
"type": "vagrant"
// ...
},
{
"type": "atlas"
// ...
}
]
]
}
```
Sequencing automatically passes the resulting artifact from one
post-processor to the next – in this case, the `.box` file.
@ -49,10 +54,12 @@ The [Vagrant post-processor](https://packer.io/docs/post-processors/vagrant.html
from the build (an `.ovf` file, for example) into a `.box` file before
passing it to the `atlas` post-processor.
{
"type": "vagrant",
"keep_input_artifact": false
}
```json
{
"type": "vagrant",
"keep_input_artifact": false
}
```
The input artifact (i.e and `.ovf` file) does not need to be kept when building Vagrant Boxes,
as the resulting `.box` will contain it.
@ -61,15 +68,17 @@ as the resulting `.box` will contain it.
The [post-processor](https://packer.io/docs/post-processors/atlas.html) takes the resulting `.box` file and uploads it adding metadata about the box version.
{
"type": "atlas",
"artifact": "%{DEFAULT_USERNAME}/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "vmware_desktop",
"version": "0.0.1"
}
}
```json
{
"type": "atlas",
"artifact": "my-username/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "vmware_desktop",
"version": "0.0.1"
}
}
```
#### Attributes Required
@ -98,31 +107,35 @@ An example post-processor block for Terraform Enterprise and Vagrant is below. I
the build runs on both VMware and Virtualbox creating two
different providers for the same box version (`0.0.1`).
"post-processors": [
[
{
"type": "vagrant",
"keep_input_artifact": false
},
{
"type": "atlas",
"only": ["vmware-iso"],
"artifact": "%{DEFAULT_USERNAME}/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "vmware_desktop",
"version": "0.0.1"
}
},
{
"type": "atlas",
"only": ["virtualbox-iso"],
"artifact": "%{DEFAULT_USERNAME}/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "virtualbox",
"version": "0.0.1"
}
```json
{
"post-processors": [
[
{
"type": "vagrant",
"keep_input_artifact": false
},
{
"type": "atlas",
"only": ["vmware-iso"],
"artifact": "my-username/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "vmware_desktop",
"version": "0.0.1"
}
]
},
{
"type": "atlas",
"only": ["virtualbox-iso"],
"artifact": "my-username/dev-environment",
"artifact_type": "vagrant.box",
"metadata": {
"provider": "virtualbox",
"version": "0.0.1"
}
}
]
]
}
```

20
website/source/docs/enterprise/packer/artifacts/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "About Packer and Artifacts"
page_title: "Packer Artifacts - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerartifacts"
description: |-
Packer creates and uploads artifacts to Terraform Enterprise.
@ -11,12 +11,12 @@ description: |-
Packer creates and uploads artifacts to Terraform Enterprise. This is done
with the [post-processor](https://packer.io/docs/post-processors/atlas.html).
Artifacts can then be used to deploy services or access
via Vagrant. Artifacts are generic, but can be of varying types.
These types define different behavior within Terraform Enterprise.
Artifacts can then be used to deploy services or access via Vagrant. Artifacts
are generic, but can be of varying types. These types define different behavior
within Terraform Enterprise.
For uploading artifacts `artifact_type` can be set to any
unique identifier, however, the following are recommended for consistency.
For uploading artifacts `artifact_type` can be set to any unique identifier,
however, the following are recommended for consistency.
- `amazon.image`
- `azure.image`
@ -33,8 +33,8 @@ unique identifier, however, the following are recommended for consistency.
- `vagrant.box`
Packer can create artifacts when running in Terraform Enterprise or locally.
This is possible due to the post-processors use of the public
artifact API to store the artifacts.
This is possible due to the post-processors use of the public artifact API to
store the artifacts.
You can read more about artifacts and their use in the [Terraform section](/docs/enterprise/)
of the documentation.
You can read more about artifacts and their use in the
[Terraform section](/docs/enterprise/) of the documentation.

63
website/source/docs/enterprise/packer/builds/build-environment.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Packer Build Environment"
page_title: "Build Environment - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-environment"
description: |-
This page outlines the environment that Packer runs in within Terraform Enterprise.
@ -8,7 +8,8 @@ description: |-
# Packer Build Environment
This page outlines the environment that Packer runs in within Terraform Enterprise.
This page outlines the environment that Packer runs in within Terraform
Enterprise.
### Supported Builders
@ -40,16 +41,20 @@ with [Packer Provisioners](https://packer.io/docs/templates/provisioners.html).
An example of this with the Shell provisioner is below.
"provisioners": [
{
"type": "shell",
"scripts": [
"scripts/vagrant.sh",
"scripts/dependencies.sh",
"scripts/cleanup.sh"
]
}
]
```json
{
"provisioners": [
{
"type": "shell",
"scripts": [
"scripts/vagrant.sh",
"scripts/dependencies.sh",
"scripts/cleanup.sh"
]
}
]
}
```
We encourage use of relative paths over absolute paths to maintain portability
between Terraform Enterprise and local builds.
@ -129,9 +134,9 @@ resource was created outside of GitHub (like using `packer push` or
### Base Artifact Variable Injection
A base artifact can be selected on the "Settings" page for a build configuration.
During each build, the latest artifact version will have it's external
ID (such as an AMI for AWS) injected as an environment variable for the
A base artifact can be selected on the "Settings" page for a build
configuration. During each build, the latest artifact version will have it's
external ID (such as an AMI for AWS) injected as an environment variable for the
environment.
The keys for the following artifact types will be injected:
@ -144,22 +149,22 @@ The keys for the following artifact types will be injected:
You can then reference this artifact in your Packer template, like this
AWS example:
```json
{
"variables": {
"base_ami": "{{env `ATLAS_BASE_ARTIFACT_AWS_AMI_ID`}}"
},
"builders": [
{
"variables": {
"base_ami": "{{env `ATLAS_BASE_ARTIFACT_AWS_AMI_ID`}}"
},
"builders": [
{
"type": "amazon-ebs",
"access_key": "",
"secret_key": "",
"region": "us-east-1",
"source_ami": "{{user `base_ami`}}"
}
]
"type": "amazon-ebs",
"access_key": "",
"secret_key": "",
"region": "us-east-1",
"source_ami": "{{user `base_ami`}}"
}
- - -
]
}
```
## Notes on Security

39
website/source/docs/enterprise/packer/builds/how-builds-run.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Running Packer Builds"
page_title: "Running - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-runbuilds"
description: |-
This briefly covers the internal process of running builds in Terraform Enterprise.
@ -8,25 +8,30 @@ description: |-
# How Packer Builds Run in Terraform Enterprise
This briefly covers the internal process of running builds in Terraform Enterprise. It's
not necessary to know this information, but may be valuable to
help understand implications of running or debugging failing
builds.
This briefly covers the internal process of running builds in Terraform
Enterprise. It's not necessary to know this information, but may be valuable to
help understand implications of running or debugging failing builds.
### Steps of Execution
1. A Packer template and directory of files is uploaded via Packer Push or GitHub
2. Terraform Enterprise creates a version of the build configuration and waits for the upload
to complete. At this point, the version will be visible in the UI even if the upload has
not completed
3. Once the upload finishes, the build is queued. This is potentially
split across multiple machines for faster processing
1. A Packer template and directory of files is uploaded via Packer Push or
GitHub
2. Terraform Enterprise creates a version of the build configuration and waits
for the upload to complete. At this point, the version will be visible in the UI
even if the upload has not completed
3. Once the upload finishes, the build is queued. This is potentially split
across multiple machines for faster processing
4. In the build environment, the package including the files and Packer template
are downloaded
5. `packer build` is run against the template in the build environment
6. Logs are streamed into the UI and stored
7. Any artifacts as part of the build are then uploaded via the public
artifact API, as they would be if Packer was executed locally
8. The build completes, the environment is teared down and status
updated
5. `packer build` is run against the template in the build environment
6. Logs are streamed into the UI and stored
7. Any artifacts as part of the build are then uploaded via the public artifact
API, as they would be if Packer was executed locally
8. The build completes, the environment is teared down and status updated

32
website/source/docs/enterprise/packer/builds/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "About Builds"
page_title: "Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds"
description: |-
Builds are instances of `packer build` being run within Terraform Enterprise.
@ -8,24 +8,28 @@ description: |-
# About Builds
Builds are instances of `packer build` being run within Terraform Enterprise. Every
build belongs to a build configuration.
Builds are instances of `packer build` being run within Terraform Enterprise.
Every build belongs to a build configuration.
__Build configurations__ represent a set of Packer configuration versions and
builds run. It is used as a namespace within Terraform Enterprise, Packer commands and URLs. Packer
configuration sent to Terraform Enterprise are stored and versioned under
these build configurations.
builds run. It is used as a namespace within Terraform Enterprise, Packer
commands and URLs. Packer configuration sent to Terraform Enterprise are stored
and versioned under these build configurations.
These __versions__ of Packer configuration can contain:
- The Packer template, a JSON file which define one or
more builds by configuring the various components of Packer
- The Packer template, a JSON file which define one or more builds by
configuring the various components of Packer
- Any provisioning scripts or packages used by the template
- Applications that use the build as part of the pipeline and merged into the version prior to running Packer on it
When a new version of Packer configuration and associated
scripts from GitHub or `packer push` is received, it automatically starts a new
Packer build. That Packer build runs in an isolated machine environment with the contents
of that version available to it.
- Applications that use the build as part of the pipeline and merged into the
version prior to running Packer on it
You can be alerted of build events with [Build Notifications](/docs/enterprise/packer/builds/notifications.html).
When a new version of Packer configuration and associated scripts from GitHub or
`packer push` is received, it automatically starts a new Packer build. That
Packer build runs in an isolated machine environment with the contents of that
version available to it.
You can be alerted of build events with
[Build Notifications](/docs/enterprise/packer/builds/notifications.html).

2
website/source/docs/enterprise/packer/builds/installing-software.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Installing Software with Packer"
page_title: "Installing Software - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-installing"
description: |-
Installing software with Packer.

25
website/source/docs/enterprise/packer/builds/managing-packer-versions.html.md
View File

@ -1,27 +1,28 @@
---
layout: "enterprise"
page_title: "Managing Packer Versions"
page_title: "Managing Packer Versions - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-versions"
description: |-
Terraform Enterprise does not automatically upgrade the version of Packer used to run builds or compiles.
Terraform Enterprise does not automatically upgrade the version of Packer used to run builds or compiles.
---
# Managing Packer Versions
Terraform Enterprise does not automatically upgrade the version of Packer
used to run builds or compiles. This is intentional, as occasionally
there can be backwards incompatible changes made to Packer that cause templates to stop
Terraform Enterprise does not automatically upgrade the version of Packer used
to run builds or compiles. This is intentional, as occasionally there can be
backwards incompatible changes made to Packer that cause templates to stop
building properly, or new versions that produce some other unexpected behavior.
All upgrades must be performed by a user, but Terraform Enterprise will display a notice
above any builds run with out of date versions. We encourage the use
of the latest version when possible.
All upgrades must be performed by a user, but Terraform Enterprise will display
a notice above any builds run with out of date versions. We encourage the use of
the latest version when possible.
### Upgrading Packer
1. Go the Settings tab of a build configuration or application
2. Go to the "Packer Version" section and select the version you
wish to use
2. Go to the "Packer Version" section and select the version you wish to use
3. Review the changelog for that version and previous versions
4. Click the save button. At this point, future builds will use that
version
4. Click the save button. At this point, future builds will use that version

4
website/source/docs/enterprise/packer/builds/notifications.html.md
View File

@ -1,9 +1,9 @@
---
layout: "enterprise"
page_title: "About Packer Build Notifications"
page_title: "Build Notifications - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-notifications"
description: |-
Terraform Enterprise can send build notifications to your organization.
Terraform Enterprise can send build notifications to your organization.
---
# About Packer Build Notifications

18
website/source/docs/enterprise/packer/builds/rebuilding.html.md
View File

@ -1,20 +1,20 @@
---
layout: "enterprise"
page_title: "Rebuilding Builds"
page_title: "Rebuilding - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-rebuilding"
description: |-
Sometimes builds fail due to temporary or remotely controlled conditions.
Sometimes builds fail due to temporary or remotely controlled conditions.
---
# Rebuilding Builds
Sometimes builds fail due to temporary or remotely controlled conditions.
In this case, it may make sense to "rebuild" a Packer build. To do so,
visit the build you wish to run again and click the Rebuild button. This
will take that exact version of configuration and run it again.
In this case, it may make sense to "rebuild" a Packer build. To do so, visit the
build you wish to run again and click the Rebuild button. This will take that
exact version of configuration and run it again.
You can rebuild at any point in history, but this may cause side effects
that are not wanted. For example, if you were to rebuild an old version
of a build, it may create the next version of an artifact that is then released,
causing a rollback of your configuration to occur.
You can rebuild at any point in history, but this may cause side effects that
are not wanted. For example, if you were to rebuild an old version of a build,
it may create the next version of an artifact that is then released, causing a
rollback of your configuration to occur.

31
website/source/docs/enterprise/packer/builds/scheduling-builds.html.md
View File

@ -1,9 +1,9 @@
---
layout: "enterprise"
page_title: "Schedule Periodic Builds"
page_title: "Schedule Periodic Builds - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-scheduling"
description: |-
Terraform Enterprise can automatically run a Packer build and create artifacts on a specified schedule.
Terraform Enterprise can automatically run a Packer build and create artifacts on a specified schedule.
---
# Schedule Periodic Builds in Terraform Enterprise
@ -12,22 +12,23 @@ Terraform Enterprise can automatically run a Packer build and
create artifacts on a specified schedule. This option is disabled by default and can be enabled by an
organization owner on a per-[environment](/docs/enterprise/glossary#environment) basis.
On the specified interval, builds will be automatically queued that
run Packer for you, creating any artifacts and sending the appropriate
notifications.
On the specified interval, builds will be automatically queued that run Packer
for you, creating any artifacts and sending the appropriate notifications.
If your artifacts are used in any other environments and you have activated
the plan on artifact upload feature, this may also queue Terraform
plans.
If your artifacts are used in any other environments and you have activated the
plan on artifact upload feature, this may also queue Terraform plans.
This feature is useful for maintenance of images and automatic updates,
or to build nightly style images for staging or development environments.
This feature is useful for maintenance of images and automatic updates, or to
build nightly style images for staging or development environments.
## Enabling Periodic Builds
To enable periodic builds for a build, visit the build settings page and select the desired interval and click the save button to persist the changes. An initial build may immediately run, depending
on the history, and then will automatically build at the specified interval.
To enable periodic builds for a build, visit the build settings page and select
the desired interval and click the save button to persist the changes. An
initial build may immediately run, depending on the history, and then will
automatically build at the specified interval.
If you have run a build separately, either manually or triggered from GitHub
or Packer configuration version uploads, Terraform Enterprise will not queue a new
build until the alloted time after the manual build ran. This ensures that a build has been executed at the specified schedule.
If you have run a build separately, either manually or triggered from GitHub or
Packer configuration version uploads, Terraform Enterprise will not queue a new
build until the allowed time after the manual build ran. This ensures that a
build has been executed at the specified schedule.

43
website/source/docs/enterprise/packer/builds/starting.html.md
View File

@ -1,6 +1,6 @@
---
layout: "enterprise"
page_title: "Starting Packer Builds in Terraform Enterprise"
page_title: "Starting - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-starting"
description: |-
Packer builds can be started in Terraform Enterprise in two ways. This post is about how.
@ -8,33 +8,36 @@ description: |-
# Starting Packer Builds in Terraform Enterprise
Packer builds can be started in in two ways: `packer push`
to upload the template and directory or via a GitHub connection that retrieves
the contents of a repository after changes to the default branch (usually
master).
Packer builds can be started in in two ways: `packer push` to upload the
template and directory or via a GitHub connection that retrieves the contents of
a repository after changes to the default branch (usually master).
### Packer Push
Packer `push` is a [Packer command](https://packer.io/docs/command-line/push.html)
that packages and uploads a Packer template and directory. This then creates a build which performs `packer build` against the uploaded template
and packaged directory.
Packer `push` is a
[Packer command](https://packer.io/docs/command-line/push.html) that packages
and uploads a Packer template and directory. This then creates a build which
performs `packer build` against the uploaded template and packaged directory.
The directory is included in order to run any associated provisioners,
builds or post-processors that all might use local files. For example,
a shell script or set of Puppet modules used in a Packer build needs
to be part of the upload for Packer to be run remotely.
The directory is included in order to run any associated provisioners, builds or
post-processors that all might use local files. For example, a shell script or
set of Puppet modules used in a Packer build needs to be part of the upload for
Packer to be run remotely.
By default, everything in your directory is uploaded as part of the push.
However, it's not always the case that the entire directory should be uploaded. Often,
temporary or cache directories and files like `.git`, `.tmp` will be included by default. This
can cause builds to fail at certain sizes and should be avoided. You can
specify [exclusions](https://packer.io/docs/templates/push.html#exclude) to avoid this situation.
However, it's not always the case that the entire directory should be uploaded.
Often, temporary or cache directories and files like `.git`, `.tmp` will be
included by default. This can cause builds to fail at certain sizes and should
be avoided. You can specify
[exclusions](https://packer.io/docs/templates/push.html#exclude) to avoid this
situation.
Packer also allows for a [VCS option](https://packer.io/docs/templates/push.html#vcs)
that will detect your VCS (if there is one) and only upload the files that are tracked by the VCS.
This is useful for automatically excluding ignored files. In a VCS
like git, this basically does a `git ls-files`.
Packer also allows for a
[VCS option](https://packer.io/docs/templates/push.html#vcs) that will detect
your VCS (if there is one) and only upload the files that are tracked by the
VCS. This is useful for automatically excluding ignored files. In a VCS like
git, this basically does a `git ls-files`.
### GitHub Webhooks

64
website/source/docs/enterprise/packer/builds/troubleshooting.html.md
View File

@ -1,15 +1,15 @@
---
layout: "enterprise"
page_title: "Troubleshooting Failing Builds"
page_title: "Troubleshooting - Packer Builds - Terraform Enterprise"
sidebar_current: "docs-enterprise-packerbuilds-troubleshooting"
description: |-
Packer builds can fail in Terraform Enterprise for a number of reasons – improper configuration, transient networking errors, and hardware constraints are all possible.
Packer builds can fail in Terraform Enterprise for a number of reasons – improper configuration, transient networking errors, and hardware constraints are all possible.
---
# Troubleshooting Failing Builds
Packer builds can fail in Terraform Enterprise for a number of reasons – improper
configuration, transient networking errors, and hardware constraints
Packer builds can fail in Terraform Enterprise for a number of reasons –
improper configuration, transient networking errors, and hardware constraints
are all possible. Below is a list of debugging options you can use.
### Verbose Packer Logging
@ -20,24 +20,27 @@ in Packer. Set the `PACKER_LOG` key to a value of `1` to accomplish this.
After setting the variable, you'll need to [rebuild](/docs/enterprise/packer/builds/rebuilding.html).
Verbose logging will be much louder than normal Packer logs and isn't
recommended for day-to-day operations. Once enabled, you'll be able to
see in further detail why things failed or what operations Packer was performing.
recommended for day-to-day operations. Once enabled, you'll be able to see in
further detail why things failed or what operations Packer was performing.
This can also be used locally:
PACKER_LOG=1 packer build ...
```text
$ PACKER_LOG=1 packer build ...
```
### Hanging Builds
Some VM builds, such as VMware or Virtualbox, may hang at various stages,
Some VM builds, such as VMware or VirtualBox, may hang at various stages,
most notably `Waiting for SSH...`.
Things to pay attention to when this happens:
- SSH credentials must be properly configured. AWS keypairs should
match, SSH usernames should be correct, passwords should match, etc.
- Any VM pre-seed configuration should have the same SSH configuration
as your template defines
- SSH credentials must be properly configured. AWS keypairs should match, SSH
usernames should be correct, passwords should match, etc.
- Any VM pre-seed configuration should have the same SSH configuration as your
template defines
A good way to debug this is to manually attempt to use the same SSH
configuration locally, running with `packer build -debug`. See
@ -49,11 +52,11 @@ Your build may be failing by requesting larger memory or
disk usage then is available. Read more about the [build environment](/docs/enterprise/packer/builds/build-environment.html#hardware-limitations).
_Typically_ Packer builds that fail due to requesting hardware limits
that exceed Terraform Enterprise's [hardware limitations](/docs/enterprise/packer/builds/build-environment.html#hardware-limitations)
that exceed Terraform Enterprise's [hardware limitations](/docs/enterprise/packer/builds/build-environment.html#hardware-limitations)
will fail with a _The operation was canceled_ error message as shown below:
```
...
```text
# ...
==> vmware-iso: Starting virtual machine...
vmware-iso: The VM will be run headless, without a GUI. If you want to
vmware-iso: view the screen of the VM, connect via VNC without a password to
@ -72,13 +75,13 @@ Build 'vmware-iso' errored: Error starting VM: VMware error: Error: The operatio
Sometimes it's faster to debug failing builds locally. In this case,
you'll want to [install Packer](https://www.packer.io/intro/getting-started/setup.html) and any providers (like Virtualbox) necessary.
Because Terraform Enterprise runs the open source version of Packer, there should be
no difference in execution between the two, other than the environment that
Packer is running in. For more on hardware constraints in the Terraform Enterprise environment
read below.
Because Terraform Enterprise runs the open source version of Packer, there
should be no difference in execution between the two, other than the environment
that Packer is running in. For more on hardware constraints in the Terraform
Enterprise environment read below.
Once your builds are running smoothly locally you can push it up to Terraform Enterprise
for versioning and automated builds.
Once your builds are running smoothly locally you can push it up to Terraform
Enterprise for versioning and automated builds.
### Internal Errors
@ -89,12 +92,13 @@ to properly unpack. This can be caused by bad permissions, using
symlinks or very large repository sizes. Using symlinks inside of the
packer directory, or the root of the repository, if the packer directory
is unspecified, will result in this internal error.
_**Note:** Most often this error occurs
when applications or builds are linked to a GitHub repository and the
directory and/or template paths are incorrect. Double check that the paths
specified when you linked the GitHub repository match the actual paths
to your template file._
- SEC-001: Your data was being unpacked from a tarball uploaded
_**Note:** Most often this error occurs when applications or builds are
linked to a GitHub repository and the directory and/or template paths are
incorrect. Double check that the paths specified when you linked the GitHub
repository match the actual paths to your template file._
- SEC-001: Your data was being unpacked from a tarball uploaded
and encountered an error. This can be caused by bad permissions, using
symlinks or very large tarball sizes.
@ -111,6 +115,6 @@ the mailing list or IRC. All bug reports should go to GitHub.
### Getting Support
If you believe your build is failing as a result of a bug in Terraform Enterprise,
or would like other support, please [email us](mailto:support@hashicorp.com).
If you believe your build is failing as a result of a bug in Terraform
Enterprise, or would like other support, please
[email us](mailto:support@hashicorp.com).