View artifact ancestry information

This topic describes how to view ancestry information stored in HCP Packer. Ancestry refers to the relationship between source artifacts, or parents, and downstream descendants, or children. Refer to Metadata storage overview for additional information about ancestry and other HCP Packer concepts.

Background

Each time Packer pushes artifact metadata to the registry, HCP Packer creates an ancestry relationship between a child version and its parent versions. When the Packer template is configured to source artifacts from an HCP Packer channel, you can view the ancestry status in the HCP Packer UI.

Ancestry relationships

The amount of detail HCP Packer can report about ancestry relationships depends on two factors. HCP Pcker can report more information when it is tracking the artifact, which means that the metadata for the artifacts was pushed to HCP Packer. Additionally, assigning parents to a channel and referencing them in your Packer template enables HCP Packer to report when a child is outdated. The following table describes how parent tracking and channel assignments affect ancestry information storage and retrieval:

Tracking parent	Parent assigned to channel	Ancestry details
No	No	HCP Packer stores the parent’s `source_external_identifier`. You can query the HCP Packer API to get this ancestry information. Refer to View ancestry for details.
Yes	No	HCP Packer creates an ancestry relationship. The ancestry status is set to `Undetermined` in the UI. You can automatically revoke each version's children. Refer to Revoke and restore artifact versions for details.
Yes	Yes	HCP Packer creates an ancestry relationship and displays the corresponding ancestry status in the UI. The UI warns you when the child is outdated. You can automatically revoke each version’s children.

Ancestry status

HCP Packer tracks ancestry status from the channel that the parent version was assigned to when Packer built the children. Refer to Create and manage channels for additional information.

The following table describes the following ancestry statuses that HCP can assign to a version:

Status	Description
`Up to date`	The version parent is currently assigned to the channel. The version may not have been built from the latest version of the parent. For example, if you rebuilt the parent without updating the channel, HCP Packer still reports all children as `Up to date`.
`Out of date`	The version's parent is not currently assigned to the channel. For example, the channel points to the latest version if you recently rebuilt the parent artifact.
`Undetermined`	HCP Packer cannot determine the child's status. The following circumstances result in `Undetermined` ancestry status:

The child is built but the parent version is not assigned to a channel
The channel no longer exists in the bucket
HCP Packer is not tracking the parent.

Requirements

Artifacts must be built with Packer v1.8.2 or later.
To view ancestry information in the UI, the artifact must be built by Packer and the metadata pushed to HCP Packer.
Parent versions must be assigned to a channel prior to building children. Refer to Create and manage channels for additional information.
Packer configurations must use channels to reference parent artifacts. Refer to Reference artifact metadata for additional information.

View ancestry

To view ancestry status from the HCP Packer UI, click on a bucket to open its Overview page. The Ancestry section displays each parent and child of the current artifact and their ancestry status.

View untracked artifact parent ancestry

Parent artifacts that are not tracked in HCP Packer are not visible from the UI. You can send a GET request to the buckets/{bucket_name}/versions/{fingerprint} API to view ancestry information for artifacts sourced from untracked parents.

The following example retrieves ancestry information using the fingerprint 01HM6MPATNN8F2MPQM7C5556M8:

$ curl –request GET https://api.cloud.hashicorp.com/packer/2023-01-01/organizations/$ORGANIZATION_ID/projects/$PROJECT_ID/buckets/my-bucket/versions/01HM6MPATNN8F2MPQM7C5556M8 --header "authorization: Bearer $HCP_ACCESS_TOKEN"

The following example response shows the parent artifacts for the child version of fingerprint 01HM6MPATNN8F2MPQM7C5556M8. You can view the parent's external identifier for each build in source_external_identifier:


{
    "version": {
        // …
        "builds": [
            {
                "id": "01G9MYAR0KHRHNA0ZSCEAK0G96",
                "version_id": "01G9MYAQCSJAXTYYHZP6WE6Z6T",
                "component_type": "amazon-ebs.basic-example",
                "packer_run_uuid": "98092f7a-11d5-663c-dde9-c0ab67407392",
                "artifacts": [
                    {
        // …
                    }
                ],
                "platform": "aws",
                "status": "DONE",
                "source_external_identifier": "ami-0688ba7eeeeefe3cd"
            }
        ]
    }
}