Revoke and restore artifact versions

This topic describes how to revoke versions of artifacts that you no longer want to make available to consumers. It also describes how to restore versions that have been revoked.

Hands on: Complete the Revoke an Artifact and its Descendents tutorial to learn about how revocation works.

Introduction

If an artifact becomes outdated or a security risk, you can revoke the outdated or unsecure version to prevent consumers from using it to build artifacts. HCP Packer marks the version as revoked in the HCP Packer UI. Packer cannot build artifacts from templates that reference a revoked version.

Workflows

You can either revoke artifacts on demand or, if you are on an HCP Packer Plus tier, schedule artifacts to be revoked later. We recommend immediately revoking artifacts that have security vulnerabilities.

Terraform configurations that reference the revoked artifact version still retrieve metadata, but HCP Packer adds the revoke_at attribute set to the timestamp of when the version was revoked. Terraform consumers can use this attribute to validate the version. Refer to Reference artifact metadata for additional information. The HCP Terraform artifact validation run task also scans the configuration and flags any planned resources that reference revoked versions. Refer to Validate builds for additional information.

Ancestry

HCP Packer automatically tracks how artifacts are related to each other to trace changes and vulnerabilities from an artifact to all of its descendants. Refer to Ancestry for more details.

When you revoke an artifact version, you can choose to automatically revoke all of its downstream descendants in HCP Packer. Doing so helps prevent consumers from using outdated artifacts. When an artifact has been revoked, the HCP Packer UI displays information about the revoked status that a child version may inherit from its parent, including a link to the revoked ancestor.

You can still schedule an earlier revocation date or immediately revoke children that are scheduled to be revoked as a result of their parent's scheduled revocation. Note that a child version may have more than one parent. Refer to Precedence for information about how HCP Packer determines revocation precedence.

Precedence

You can explicitly revoke a child artifact version or revoke its parent so that the child inherits the revocation. An artifact version can have multiple parents. As a result, a child can inherit multiple revocations. When multiple revocations apply, HCP Packer uses the following rules to determine revocation precedence:

1. Explicit revocation: Explicitly revoking the version, either on demand or scheduled, takes precedence over all inherited revocations. If a version is revoked multiple times, the earliest date takes precedence.

2. Earliest revocation: When a child inherits multiple revocations, the earliest revocation date takes precedence. For example, if you schedule ancestor A for revocation at 5 PM and then schedule ancestor B for revocation at 4 PM the same day, HCP Packer revokes the child version at 4 PM.

Requirements

A Plus tier is required to schedule revocation. Refer to Manage registry for details about viewing and changing your registry tier.

Revoke an artifact version

1. Click Versions in the sidebar to view a list of all versions within a bucket.
2. Open the ellipses menu for the version you want to revoke and choose Revoke Version.
3. (Optional) Enter an explanation for revoking the version in the Reason field. HCP Packer shows this message on the version details page after the version has been revoked.
4. If you are on a tier that enables you to schedule a revocation, choose Revoke immediately from the When dropdown menu.
5. Choose Yes, revoke all descendants or No, only revoke version from the Revoke descendants? dropdown menu. Refer to Ancestry for additional information.
6. If this version is assigned to a user-created channel, choose Yes, rollback channel from the Rollback channels dropdown menu to reassign the last valid and unrevoked version to each channel. Otherwise, you must manually un-assign the version from all user-created channels before proceeding.
7. Click Revoke.

You can restore the version at any time.

Schedule an artifact version to be revoked

You can set a time to live (TTL) on artifacts, which prevents consumers from using outdated artifacts. An HCP Packer Plus tier is required. Refer to Requirements for additional information.

1. Click Versions in the sidebar to view a list of all versions within a bucket.
2. Open the ellipses menu for the version you want to revoke and choose Revoke Version.
3. (Optional) Enter an explanation for revoking the version in the Reason field. HCP Packer shows this message on the version details page after the version has been revoked.
4. Choose Revoke at a future date from the When dropdown and specify a date and time. Consumers can use this version's metadata until the specified date and time.
5. Choose whether to schedule the revocation for all descendant versions. Refer to Ancestry for additional information.
6. If this version is assigned to a user-created channel, choose Yes, rollback channel from the Rollback channel dropdown menu to reassign the last valid and unrevoked version to each channel when HCP Packer revokes the version. If the channel has a valid version assigned at the time of scheduled revocation, no rollback occurs.
7. Click Revoke.

The HCP Packer UI indicates that the version is scheduled to be revoked on the version details screen and adds a tag on any associated channels. Consumers can continue to use the version until the specified date and time that HCP Packer is scheduled to revoke the version.

You can cancel the revoke action any time before it occurs. Refer to Cancel a scheduled revocation for additional information.

At the specified date and time, HCP Packer marks channels that point to revoked versions with a Revoked tag in the UI. We recommend notifying consumers and removing the revoked version from all associated channels.

Restore a version

Revoked versions remain available in HCP Packer until you manually delete them from your registry. You can restore them so that their metadata is available to consumers.

1. Go to the version's details page and click Restore version.
2. When prompted, click Restore version to confirm that you want to restore the version.

The restored version metadata is immediately available to consumers. HCP Packer removes the Revoked tag in the UI. HCP Packer does not automatically re-add artifacts to channels. As a result, you must manually re-add the artifact to any previously associated channels.

You cannot restore a version if an ancestor version has been revoked. Restore the revoked ancestor to automatically restore all of its descendants. Refer to Ancestry for additional information.

Cancel a scheduled revocation

You can cancel a scheduled revocation any time before the specified date.

1. Go to the version's details page and click Cancel scheduled revoke.
2. When prompted, click Cancel scheduled revoke to confirm that you want to prevent the version from being revoked.

The HCP Packer UI removes the Scheduled for revoke status in the UI.

You cannot cancel a revocation for a child version when an ancestor version is scheduled to be revoked. Cancel the scheduled revocation for the ancestor to automatically cancel the revocation for all of its descendants. Refer to Ancestry for additional information.