Manage OCI Artifacts and Supply Chain Artifacts with ORAS
Article
Azure container registry (ACR) helps you manage both the Open container initiative (OCI) artifacts and supply chain artifacts. This article guides you how to use ACR for managing OCI artifacts and supply chain artifacts effectively. Learn to store, manage, and retrieve both OCI artifacts and a graph of supply chain artifacts, including signatures, software bill of materials (SBOM), security scan results, and other types.
Azure container registry - Create a container registry in your Azure subscription. For example, use the Azure portal or the Azure CLI.
Azure CLI - Version 2.29.1 or later is required. See Install Azure CLI for installation and/or upgrade.
ORAS CLI - Version v1.1.0 or later version is required. See: ORAS installation.
Docker (Optional) - To complete the walkthrough, a container image is referenced. The oras CLI utilizes the Docker desktop credential store for storing credentials.
You can use Docker installed locally to build and push a container image, or use acr build to build remotely in Azure.
Configure the registry
To configure your environment for easy command execution, follow these steps:
Set the ACR_NAME variable to your registry name.
Set the REGISTRY variable to $ACR_NAME.azurecr.io.
Set the REPO variable to your repository name.
Set the TAG variable to your desired tag.
Set the IMAGE variable to $REGISTRY/${REPO}:$TAG.
Set environment variables
Configure a registry name, login credentials, a repository name, and tag to push and pull artifacts. The following example uses the net-monitor repository name and v1 tag. Replace with your own repository name and tag.
Authenticate with the ACR, for allowing you to pull and push container images.
Azure CLI
az login az acr login -n$REGISTRY
This setup enables you to seamlessly push and pull artifacts to and from your Azure Container Registry. Now ORAS can be used with ACR without additional authentication by using oras login command.
If Docker isn't available, you can use the AD token provided for authentication. Authenticate with your individual Microsoft Entra identity using an AD token. Always use "000..." for the USER_NAME as the token is parsed through the PASSWORD variable. The token used by az acr login is valid for three hours.
Note
ACR and ORAS support multiple authentication options for users and system automation. This article uses individual identity for demonstration convenience. For more authentication options see Authenticate with an Azure container registry..
To demonstrate this capability, this section shows how to use the OCI Registry as Storage (ORAS) CLI to push and pull OCI artifacts to/from an Azure container registry. You can manage various OCI artifacts in an Azure container registry using different command-line tools appropriate to each artifact.
Push an artifact
A single file artifact that has no subject parent can be anything from a container image, a helm chart, a readme file for the repository. Reference artifacts can be anything from a signature, software bill of materials, scan reports, or other evolving types. Reference artifacts, described in Attach, push, and pull supply chain artifacts are artifacts that refer to another artifact.
Push a Single-File Artifact
For this example, create content that represents a markdown file:
Bash
echo'Readme Content' > readme.md
The following step pushes the readme.md file to <myregistry>.azurecr.io/samples/artifact:readme.
The registry is identified with the fully qualified registry name <myregistry>.azurecr.io (all lowercase), followed by the namespace and repo: /samples/artifact.
The artifact is tagged :readme, to identify it uniquely from other artifacts listed in the repo (:latest, :v1, :v1.0.1).
Setting --artifact-type readme/example differentiates the artifact from a container image, which uses application/vnd.oci.image.config.v1+json.
The ./readme.md identifies the file uploaded, and the :application/markdown represents the IANA mediaType of the file.
For more information, see OCI Artifact Authors Guidance.
Use the oras push command to push the file to your registry.
When OCI artifacts are pushed to a registry with ORAS, each file reference is pushed as a blob. To push separate blobs, reference the files individually, or collection of files by referencing a directory.
For more information how to push a collection of files, see Pushing artifacts with multiple files.
Attach, push, and pull supply chain artifacts with ORAS
To demonstrate this capability, this article shows how to use the OCI Registry as Storage (ORAS) CLI to push, discover, and pull a graph of supply chain artifacts to an Azure container registry.
Storing individual (subject) OCI Artifacts are covered in Push and pull OCI artifacts.
Attach a signature to the registry, as a reference to the container image
The oras attach command creates a reference between the file (./signature.json) to the $IMAGE. The --artifact-type provides for differentiating artifacts, similar to file extensions that enable different file types. One or more files can be attached by specifying [file]:[mediaType].
When OCI artifacts are pushed to a registry with ORAS, each file reference is pushed as a blob. To push separate blobs, reference the files individually, or collection of files by referencing a directory.
For more information how to push a collection of files, see Pushing artifacts with multiple files.
Discovering artifact references
The OCI v1.1 Specification defines a referrers API for discovering references to a subject artifact. The oras discover command can show the list of references to the container image.
Using oras discover, view the graph of artifacts now stored in the registry.
Bash
oras discover -o tree $IMAGE
The output shows the beginning of a graph of artifacts, where the signature and docs are viewed as children of the container image.
Microsoft recommends using a secure crypto signing tool, like Notation to sign the image and generate a signature for signing SBOMs.
Artifacts that are pushed as references, typically don't have tags as they're considered part of the subject artifact. To push a signature to an artifact that is a child of another artifact, use the oras discover with --artifact-type filtering to find the digest. This example uses a simple JSON signature for demonstration purposes.
A typical DevOps workflow promotes artifacts from dev through staging, to the production environment. Secure supply chain workflows promote public content to privately secured environments.
In either case you want to promote the signatures, SBOMs, scan results, and other related artifact with the subject artifact to have a complete graph of dependencies.
Using the oras copy command, you can promote a filtered graph of artifacts across registries.
Copy the net-monitor:v1 image, and related artifacts to sample-staging/net-monitor:v1:
ORAS enables artifact graphs to be pushed, discovered, pulled, and copied without having to assign tags. It also enables a tag listing to focus on the artifacts users think about, as opposed to the signatures and SBOMs that are associated with the container images, helm charts, and other artifacts.
View a list of tags
Bash
oras repo tags $REGISTRY/$REPO
Deleting all artifacts in the graph
Support for the OCI v1.1 Specification enables deleting the graph of artifacts associated with the subject artifact. Use the oras manifest delete command to delete the graph of artifacts (signature, SBOM, and the signature of the SBOM).
You can view the list of manifests to confirm the deletion of the subject artifact, and all related artifacts leaving a clean environment.
Azure CLI
az acr manifest list-metadata \
--name$REPO \
--registry$ACR_NAME-o jsonc
Output:
Output
2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.
Summary
In this article, you learned how to use Azure Container Registry to store, manage, and retrieve both OCI artifacts and supply chain artifacts. You used ORAS CLI to push and pull artifacts to/from an Azure Container Registry. You also discovered the manifest of the pushed artifacts and viewed the graph of artifacts attached to the container image.
Next steps
Learn about Artifact References, associating signatures, software bill of materials and other reference types.
Learn more about the ORAS Project, including how to configure a manifest for an artifact.
Visit the OCI Artifacts repo for reference information about new artifact types.