github.com/hashicorp/packer@v1.14.3/website/content/docs/hcp/index.mdx (about)

     1  ---
     2  description: |
     3    Packer can publish metadata for completed builds to the HCP Packer registry. Learn how to connect Packer to the HCP Packer registry.
     4  page_title: Connect to the HCP Packer registry overview
     5  ---
     6  
     7  # Connect to the HCP Packer Registry
     8  
     9  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
    10  [Packer Template Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration) page in the HCP
    11  Packer documentation for configuration details and examples.
    12  
    13  # Introduction
    14  
    15  The HCP Packer registry bridges the gap between artifact factories and artifact deployments, allowing development and
    16  security teams to work together to create, manage, and consume artifacts in a centralized way.
    17  
    18  The HCP Packer Registry stores metadata about your artifact, including when they were created, where the artifact
    19  exists on the external platform, and what (if any) git commit is associated with your build. You can use the registry
    20  to track information about the artifact your Packer builds produce, clearly designate which artifact are appropriate
    21  for test and production environments, and query for the right artifact to use in both Packer and Terraform
    22  configurations.
    23  
    24  You can use HCP Packer with both JSON and HCL2 templates. If you are using JSON templates, we recommend getting started with
    25  the [HCP Packer environment variables](#hcp-packer-environment-variables) and then migrating to HCL when possible.
    26  
    27  ## Requirements
    28  
    29  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.
    30  
    31  ## HCP Packer environment variables
    32  
    33  The following environment variables let you configure Packer to push artifact metadata to an active registry without
    34  changing your template. You can use environment variables with both JSON and HCL2 templates.
    35  Refer to [Basic Configuration With Environment Variables](/hcp/docs/packer/store-image-metadata/packer-template-configuration#basic-configuration-with-environment-variables)
    36  in the HCP Packer documentation for complete instructions and examples.
    37  
    38  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
    39  
    40  For client ID and secret, you set the following environemnt variables
    41  
    42  - `HCP_CLIENT_ID`          - The HCP client ID of a HashiCorp Cloud Platform service principle that Packer can use to
    43  authenticate to an HCP Packer Registry.
    44  
    45  - `HCP_CLIENT_SECRET`      - The HCP client secret of the HashiCorp Cloud Platform service principle that Packer
    46  can use to authenticate to an HCP Packer Registry.
    47  
    48  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`
    49  
    50  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
    51  
    52  - `HCP_PACKER_BUCKET_NAME` - The name of the HCP Packer Bucket where you want HCP Packer to store artifact metadata
    53  from builds associated with your template. HCP Packer automatically creates the bucket if it does not already exist.
    54  If your HCL2 template contains an `hcp_packer_registry` block, the bucket name specified in the configuration will be
    55  overwritten by this environment variable.
    56  
    57  You can set these additional environment variables to control how metadata is pushed to the registry.
    58  
    59  - `HCP_PACKER_BUILD_FINGERPRINT` - A unique identifier assigned to each version. To reuse a fingerprint that is
    60  associated with an existing incomplete version you must set this environment variable. Refer to
    61  [Version Fingerprinting](#version-fingerprinting) for usage details.
    62  
    63  - `HCP_PACKER_REGISTRY`    -  When set, Packer does not push artifact metadata to HCP Packer from an otherwise
    64  configured template. Allowed values are [0|OFF].
    65  
    66  - `HCP_ORGANIZATION_ID` - The ID of the HCP organization linked to your service principal. This is environment
    67  variable is not required and available for the sole purpose of keeping parity with the HCP SDK authentication options.
    68  Its use may change in a future release.
    69  
    70  - `HCP_PROJECT_ID`  - The ID of the HCP project to use. This is useful if your service principal has access to multiple
    71  projects, as by default Packer will pick the one created first as target.
    72  
    73  -> **Note**: The HCP_PROJECT_ID environment variable must be set if you're authenticating with a project-level service
    74  principal, otherwise Packer will attempt to get the list of projects for an organization and error due to a lack of
    75  permissions for a project-level service principal. This is supported starting with Packer 1.9.3; older versions of
    76  Packer do not support using project-level service principals.
    77  
    78  ## HCP Packer registry block
    79  
    80  The only metadata that Packer can infer from a template with the basic configuration are the build name and build fingerprint.
    81  For HCL2 templates, we recommend adding the `hcp_packer_registry` block to your template so that you can customize
    82  the metadata that Packer sends to the registry.
    83  
    84  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.
    85  
    86  Refer to [`hcp_packer_registry`](/packer/docs/templates/hcl_templates/blocks/build/hcp_packer_registry) for a full list
    87  of configuration arguments. Refer to [Custom Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration#custom-configuration)
    88  in the HCP Packer documentation for information and examples about how to customize artifact metadata.
    89  
    90  ## Version fingerprinting
    91  
    92  Packer uses a unique fingerprint for tracking the completion of builds associated to a version. By default a fingerprint
    93  is automatically generated by Packer during each invocation of `packer build`, unless a fingerprint is manually provided
    94  via the `HCP_PACKER_BUILD_FINGERPRINT` environment variable.
    95  
    96  In versions before 1.9.0, this fingerprint was computed from the Git SHA of the current HEAD in which your template is
    97  stored. If you were running builds using a non Git managed template, you had to set the `HCP_PACKER_BUILD_FINGERPRINT`
    98  environment variable prior to invoking `packer build`.
    99  Starting with Packer 1.9.0, fingerprint generation does not rely on Git at all, and instead Packer now generates
   100  a Unique Lexicographically sortable Identifier (ULID) as the fingerprint for every `packer build` invocation.
   101  
   102  ### Fingerprints and incomplete versions
   103  
   104  When you build a template with Packer, there's always a chance that it does not succeed because of a network issue,
   105  a provisioning failure, or some upstream error. When that happens, Packer will output the generated fingerprint
   106  associated with the incomplete version so that you can resume building that version using the `HCP_PACKER_BUILD_FINGERPRINT`
   107  environment variable; a version can be resumed until it is marked as complete. This environment variable is necessary
   108  for resuming an incomplete version, otherwise Packer will create a new version for the build.
   109  
   110  There are two alternatives for when and how to set your own fingerprint:
   111  
   112  * You can set it prior to invoking `packer build` for the first time on this template. This will require the
   113  fingerprint to be unique, otherwise Packer will attempt to continue the version with the same fingerprint.
   114  * You can invoke `packer build` on the template, and if it fails, you can then get the fingerprint from the output of
   115  the command and set it for subsequent runs, Packer will then continue building this version.
   116  
   117  The first alternative is recommended for CI environments, as you can use environment variables from the CI to generate
   118  a unique, deterministic, fingerprint, and then re-use this in case the step fails for any reason. This will let you
   119  continue building the same version, rather than creating a new one on each invocation.
   120  
   121  The second alternative is good for local builds, as you can interact with the build environment directly, and therefore
   122  can decide if you want to continue building a version by setting the fingerprint provided by Packer in case of failure.
   123  
   124  Please note that in all cases, a version can only be continued if it has not completed yet. Once a version is
   125  complete, it cannot be modified, and you will have to create a new one.