Annotate Registry Artifacts

Attach OCI annotations to existing registry artifacts (such as container images or OCI artifacts) by attaching an annotations file using ORAS Reference Types.

NOTE: This only works for registries supporting OCI Artifacts, ORAS Artifacts, and ORAS Artifact Reference Types. This tool has been tested with Azure Container Registry.

Scenario

This tool is for you if you are a:

• Registry Owner/Maintainer/Administrator
• Registry Artifacts and Container Images:
  • Image/Artifact Builder
  • Image/Artifact Maintainer
  • Image/Artifact Publisher

Registry owners and artifact maintainers may wish to add custom OCI annotations to existing images within a registry. Common annotation scenarios include:

• Annotation for image end-of-life date (EOL Date), which may or may not be known during image build time.
• Annotation for image deprecation (marking an image as deprecated).
• Annotation to note the date of a recent vulnerability scan.
• Annotation marking an image as an "official image", "golden image", "preferred image", or "premium image".
• Annotation for image compliance status, such as an image's compliance and certification to run in secure-cloud and government-cloud environments.

By design, directly modifying or adding OCI annotations to an existing registry artifact is not possible after an artifact (such as a container image) has been built. This is not possible as doing so would modify the hash digest of the existing registry artifact.

Additionally, various build tools for container images currently do not support adding OCI Annotations during Dockerfile image build.

This tool:

• creates a new annotation file containing the OCI Annotations you wish to add to an existing registry artifact,
• pushes the annotation file to the same registry and repository as the existing registry artifact,
• links the annotation file and the existing artifact using ORAS Artifact References.

This allows users to query and discover (using ORAS) the annotations of existing registry artifacts and container images.

Quick Start

Install

To install, run the following commands.

curl -LO https://github.com/johnsonshi/annotate-registry-artifacts/releases/download/v0.0.1/annotation
chmod +x annotation
sudo mv annotation /usr/local/bin

Attach

This command attaches a set of OCI annotations to an existing registry artifact (such as container images or OCI artifacts).

Attach – Usage

./bin/annotation attach \
  --username "$registry_username" \
  --password "$registry_password" \
  --registry "$registry_url" \
  --subject-repository "$repository_name" \
  --subject-tag-or-digest "$digest" \
  --annotation "org.opencontainers.image.source: https://www.github.com/user/repo/source" \
  --annotation "org.opencontainers.image.authors: EFGH Inc." \
  --annotation "org.opencontainers.image.vendor: ABCD Inc." \
  --annotation "org.opencontainers.image.licenses: ABCD Image License" \
  --annotation "com.example.image.custom.key1: val1" \
  --annotation "com.example.image.custom.key2: val2"

Attach – Result

Additional Resources

For detailed explanations, please read the detailed documentation page.