mirror of https://github.com/hashicorp/packer
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
126 lines
8.5 KiB
126 lines
8.5 KiB
---
|
|
description: |
|
|
Packer can publish metadata for completed builds to the HCP Packer registry. Learn how to connect Packer to the HCP Packer registry.
|
|
page_title: Connect to the HCP Packer registry overview
|
|
---
|
|
|
|
# Connect to the HCP Packer Registry
|
|
|
|
This topic provides an overview of how to connect JSON and HCL2 templates to the HCP Packer registry and provides a full list of HCP Packer environment variables. Refer to the
|
|
[Packer Template Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration) page in the HCP
|
|
Packer documentation for configuration details and examples.
|
|
|
|
# Introduction
|
|
|
|
The HCP Packer registry bridges the gap between artifact factories and artifact deployments, allowing development and
|
|
security teams to work together to create, manage, and consume artifacts in a centralized way.
|
|
|
|
The HCP Packer Registry stores metadata about your artifact, including when they were created, where the artifact
|
|
exists on the external platform, and what (if any) git commit is associated with your build. You can use the registry
|
|
to track information about the artifact your Packer builds produce, clearly designate which artifact are appropriate
|
|
for test and production environments, and query for the right artifact to use in both Packer and Terraform
|
|
configurations.
|
|
|
|
You can use HCP Packer with both JSON and HCL2 templates. If you are using JSON templates, we recommend getting started with
|
|
the [HCP Packer environment variables](#hcp-packer-environment-variables) and then migrating to HCL when possible.
|
|
|
|
## Requirements
|
|
|
|
Packer version 1.9.1 or newer is required to use the `HCP_PROJECT_ID` environment variable, which lets Packer connect to specific projects in HCP. Your builds will fail if you configure them to send mulit-project metadata using Packer versions older than 1.9.1.
|
|
|
|
## HCP Packer environment variables
|
|
|
|
The following environment variables let you configure Packer to push artifact metadata to an active registry without
|
|
changing your template. You can use environment variables with both JSON and HCL2 templates.
|
|
Refer to [Basic Configuration With Environment Variables](/hcp/docs/packer/store-image-metadata/packer-template-configuration#basic-configuration-with-environment-variables)
|
|
in the HCP Packer documentation for complete instructions and examples.
|
|
|
|
You must set authentication environment variables to connect to HCP Packer, you can either directly set a client ID and secret, or (on Packer versions 1.14.2 and later) use an HCP certificate file
|
|
|
|
For client ID and secret, you set the following environemnt variables
|
|
|
|
- `HCP_CLIENT_ID` - The HCP client ID of a HashiCorp Cloud Platform service principle that Packer can use to
|
|
authenticate to an HCP Packer Registry.
|
|
|
|
- `HCP_CLIENT_SECRET` - The HCP client secret of the HashiCorp Cloud Platform service principle that Packer
|
|
can use to authenticate to an HCP Packer Registry.
|
|
|
|
For certificate based auth simply specify the location of the valid HCP certificate file in the `HCP_CRED_FILE` environment variable, or place it in the default location for the HCP SDK, `~/.config/hcp/cred_file.json`
|
|
|
|
See the following HCP docs for more information on [Workload Identity Federation](https://developer.hashicorp.com/hcp/docs/hcp/iam/service-principal/workload-identity-federation) and certificate authentication
|
|
|
|
- `HCP_PACKER_BUCKET_NAME` - The name of the HCP Packer Bucket where you want HCP Packer to store artifact metadata
|
|
from builds associated with your template. HCP Packer automatically creates the bucket if it does not already exist.
|
|
If your HCL2 template contains an `hcp_packer_registry` block, the bucket name specified in the configuration will be
|
|
overwritten by this environment variable.
|
|
|
|
You can set these additional environment variables to control how metadata is pushed to the registry.
|
|
|
|
- `HCP_PACKER_BUILD_FINGERPRINT` - A unique identifier assigned to each version. To reuse a fingerprint that is
|
|
associated with an existing incomplete version you must set this environment variable. Refer to
|
|
[Version Fingerprinting](#version-fingerprinting) for usage details.
|
|
|
|
- `HCP_PACKER_REGISTRY` - When set, Packer does not push artifact metadata to HCP Packer from an otherwise
|
|
configured template. Allowed values are [0|OFF].
|
|
|
|
- `HCP_ORGANIZATION_ID` - The ID of the HCP organization linked to your service principal. This is environment
|
|
variable is not required and available for the sole purpose of keeping parity with the HCP SDK authentication options.
|
|
Its use may change in a future release.
|
|
|
|
- `HCP_PROJECT_ID` - The ID of the HCP project to use. This is useful if your service principal has access to multiple
|
|
projects, as by default Packer will pick the one created first as target.
|
|
|
|
-> **Note**: The HCP_PROJECT_ID environment variable must be set if you're authenticating with a project-level service
|
|
principal, otherwise Packer will attempt to get the list of projects for an organization and error due to a lack of
|
|
permissions for a project-level service principal. This is supported starting with Packer 1.9.3; older versions of
|
|
Packer do not support using project-level service principals.
|
|
|
|
## HCP Packer registry block
|
|
|
|
The only metadata that Packer can infer from a template with the basic configuration are the build name and build fingerprint.
|
|
For HCL2 templates, we recommend adding the `hcp_packer_registry` block to your template so that you can customize
|
|
the metadata that Packer sends to the registry.
|
|
|
|
The `hcp_packer_registry` block is only available for HCL2 Packer templates. There is no [`PACKER_CONFIG`](/packer/docs/configure#packer-s-config-file) equivalent for JSON.
|
|
|
|
Refer to [`hcp_packer_registry`](/packer/docs/templates/hcl_templates/blocks/build/hcp_packer_registry) for a full list
|
|
of configuration arguments. Refer to [Custom Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration#custom-configuration)
|
|
in the HCP Packer documentation for information and examples about how to customize artifact metadata.
|
|
|
|
## Version fingerprinting
|
|
|
|
Packer uses a unique fingerprint for tracking the completion of builds associated to a version. By default a fingerprint
|
|
is automatically generated by Packer during each invocation of `packer build`, unless a fingerprint is manually provided
|
|
via the `HCP_PACKER_BUILD_FINGERPRINT` environment variable.
|
|
|
|
In versions before 1.9.0, this fingerprint was computed from the Git SHA of the current HEAD in which your template is
|
|
stored. If you were running builds using a non Git managed template, you had to set the `HCP_PACKER_BUILD_FINGERPRINT`
|
|
environment variable prior to invoking `packer build`.
|
|
Starting with Packer 1.9.0, fingerprint generation does not rely on Git at all, and instead Packer now generates
|
|
a Unique Lexicographically sortable Identifier (ULID) as the fingerprint for every `packer build` invocation.
|
|
|
|
### Fingerprints and incomplete versions
|
|
|
|
When you build a template with Packer, there's always a chance that it does not succeed because of a network issue,
|
|
a provisioning failure, or some upstream error. When that happens, Packer will output the generated fingerprint
|
|
associated with the incomplete version so that you can resume building that version using the `HCP_PACKER_BUILD_FINGERPRINT`
|
|
environment variable; a version can be resumed until it is marked as complete. This environment variable is necessary
|
|
for resuming an incomplete version, otherwise Packer will create a new version for the build.
|
|
|
|
There are two alternatives for when and how to set your own fingerprint:
|
|
|
|
* You can set it prior to invoking `packer build` for the first time on this template. This will require the
|
|
fingerprint to be unique, otherwise Packer will attempt to continue the version with the same fingerprint.
|
|
* You can invoke `packer build` on the template, and if it fails, you can then get the fingerprint from the output of
|
|
the command and set it for subsequent runs, Packer will then continue building this version.
|
|
|
|
The first alternative is recommended for CI environments, as you can use environment variables from the CI to generate
|
|
a unique, deterministic, fingerprint, and then re-use this in case the step fails for any reason. This will let you
|
|
continue building the same version, rather than creating a new one on each invocation.
|
|
|
|
The second alternative is good for local builds, as you can interact with the build environment directly, and therefore
|
|
can decide if you want to continue building a version by setting the fingerprint provided by Packer in case of failure.
|
|
|
|
Please note that in all cases, a version can only be continued if it has not completed yet. Once a version is
|
|
complete, it cannot be modified, and you will have to create a new one.
|