Ancestry

Ancestry refers to the relationship between source images (parents) and their downstream descendants (children). The HCP Packer UI can display ancestry statuses that warn you if an image was built from an old version of one or more ancestors.

This page explains how HCP Packer creates ancestry relationships and how to retrieve ancestry information.

Ancestry Relationships

Every time Packer pushes image metadata to the registry, HCP Packer creates an ancestry relationship between the new image iteration (child) and its source iterations (parents), if any.

The amount of detail HCP Packer can report about ancestry relationships depends upon whether HCP Packer is tracking the parent images and whether your Packer template uses image channels.

• If HCP Packer is not tracking a parent image, HCP Packer stores the parent’s image ID. You can query the HCP Packer API to get this ancestry information. Refer to Ancestry API for details.
• If HCP Packer is tracking a parent image but the parent is not assigned to an image channel, HCP Packer creates an ancestry relationship, but shows an Undetermined ancestry status in the UI. The ancestry relationship lets you automatically revoke each iteration’s downstream descendants. Refer to Inherited Revocation for details.
• If your Packer template uses image channels to reference parent images, HCP Packer creates an ancestry relationship and displays the corresponding ancestry status in the UI. The status warns you when the child is outdated, and the ancestry relationship lets you automatically revoke each iteration’s downstream descendants.

Ancestry Status

HCP Packer tracks ancestry status from the image channel the parent iteration was assigned to when Packer built the children. You specify this image channel in your Packer template hcp-packer-image or hcp-packer-iteration data source block.

An iteration can have one of the following ancestry statuses:

• Up to date: The iteration's parent is currently assigned to the image channel. This does not necessarily mean that the iteration is built from the latest version of the parent. For example, if you rebuilt the parent without updating the image channel, HCP Packer still reports all child images as Up to date.
• Out of date: The iteration's parent is not currently assigned to the image channel. For example, you may have recently rebuilt the parent image, and the image channel now points to the latest iteration.
• Undetermined: HCP Packer cannot determine whether the child image is out of date. This status occurs when the parent iteration was not assigned to an image channel when the child was built, the image channel no longer exists in the image bucket, or HCP Packer is not tracking the parent.

Requirements

Your workflow must meet the following requirements for HCP Packer to report ancestry status:

• Build images with Packer version >= 1.8.2.
• Assign parent image iterations to an image channel before you build children. HCP Packer uses the image channel to report the ancestry status of that parent-child relationship over time.
• Use image channels to reference parent images in your configuration.

The following example uses an hcp-packer-image data source to reference the development image channel.

data "hcp-packer-image" "ubuntu_us_east_2" {
    bucket_name     = "learn-packer-ubuntu"
    channel         = "development"
    cloud_provider  = "aws"
    region          = "us-east-2"
}

source "amazon-ebs" "ubuntu-example" {
    // ... 
    source_ami = data.hcp-packer-image.ubuntu_us_east_2.id
    // ...
}

View Ancestry Status

To view ancestry status, click an image bucket to open its Overview page. The Ancestry section displays each parent and child of the current image and their ancestry status.

The registry overview page displays an overall ancestry status for all parents and all children for each image bucket.

• The overall status is Out of date when at least one parent or child is out of date. For example, if Image A has two children and one of them is outdated, the overall status shows Out of date.
• The overall status is Undetermined when HCP Packer cannot determine the status for all parents or children in that group. For example, if Image B has two parents, and one is Up to date, the overall status shows Up to date, even if HCP Packer cannot determine the status for the other parent.

Ancestry API

The HCP Packer UI can only display ancestry information when the registry is tracking both the parent and child images. However, HCP Packer still records ancestry information for untracked images. You can use the API to check ancestry for untracked images.

Call Get Iteration. The API returns information about the iteration and builds within the specified iteration. If the build has a parent image, the parent's identifier is available in source_image_id.

The following example shows an API response containing the source_image_id for the parent image. Some portions of the response are omitted for clarity.

{
    "iteration": {
        // …
        "builds": [
            {
                "id": "01G9MYAR0KHRHNA0ZSCEAK0G96",
                "iteration_id": "01G9MYAQCSJAXTYYHZP6WE6Z6T",
                "component_type": "amazon-ebs.basic-example",
                "packer_run_uuid": "98092f7a-11d5-663c-dde9-c0ab67407392",
                "images": [
                    {
        // …
                    }
                ],
                "cloud_provider": "aws",
                "status": "DONE",
                "source_image_id": "ami-0688ba7eeeeefe3cd"
            }
        ]
    }
}