1. Portable backup & restore of repositories and artifacts
2. Multi-platform image and artifact management
3. Rich formatted output for scripting and pipelines

Moreover, ORAS is now fully compliant with OCI distribution-spec v1.1.1.

Your Registry’s Safety Net: Portable Backup & Restore​

With oras backup and oras restore, ORAS now lets you save your registry content into local directories or tarballs (OCI image layout format) as a snapshot and restore to any registry. All manifests and optionally any tags, referrers will be included within the backup.

Use cases include:

• Air-Gapped Environments: Organizations operating in isolated or high-security environments can use oras backup to export artifacts from a registry to local filesystem, and use oras restore to import them into an internal registry with restricted access.
• Disaster Recovery and Audit Archival: Take periodic snapshots of repositories and store them off-site. In case of accidental deletions, outages, and long-term storage to support regulatory audits, oras restore can be used to quickly recover full registry content.
• Registry Migration: When moving from one container registry provider to another, the pair of commands enables a full repository export, preserving tags, manifests, layers, and referrers.
• Compliance and supply chain security guarantee: Backup and restore the images along with their supply chain artifacts, such as SBOMs, signatures, vulnerability scanning reports.
• Repository Duplication or Promotion: Move artifacts from dev to staging to prod registries reliably using an intermediate backup file.

Check out the user guide Backup and Restore of OCI Artifacts, Images, and Repositories for details.

Multi-platform Image and Artifact Management​

Multi-platform images are commonly used in IoT and Edge computing, particularly heterogeneous deployments. In addition, OpenTofu or Terraform modules are packed as platform-specific artifacts and stored as multi-platform artifact in OCI registries. Thanks to our community partner OpenTofu, now multi-platform artifact management is introduced in v1.3.0.

With oras manifest index create and oras manifest index update, you can easily assemble, update, distribute, and annotate multi-architecture images and artifacts across local environments and registries. Check out the user guide Create and Manage Multi-architecture Artifacts for details.

Enable Scripting and Automation: Formatted Output​

In automation pipelines, the difference between human-readable and machine-usable output can be the difference between clarity and chaos.

With this release, ORAS enables users to use the --format flag to format metadata output into structured data (e.g. JSON) and optionally use the --template flag with the Go template language. This has been enabled for commands like pull, push, attach, discover, and manifest fetch with support for output formats including JSON, Go templates, trees, and tables. You can even run computations with Sprig template functions as well.

• Use --format <DATA_FORMAT> to transform the output of ORAS commands into different formats including prettified JSON, tree, table view, and Go template, i.e. --format json|tree|table|go-template=GO_TEMPLATE.
• Use --template GO_TEMPLATE to compute and manipulate the output using Go templates based on the chosen data format.

Formatted output transforms ORAS from a simple terminal user tool to a DevOps-friendly, integrable developer tool. Check out the user guide Formatted output for details.

Stability & User Experience Polish​

This release also includes a number of enhancements that provides a better overall user experience and stability.

• Feature Stability Promotions: oras attach, oras pull --include-subject, and more are now Stable. oras resolve from Experimental to Preview.
• Discover UX: oras discover now displays referrers recursively by default; The maximum recursion depth can be controlled via the --depth flag
• Loong64 support: More platform options including loong64 open for users.
• Developer experience: Enhanced clarity within error messages, debugging logs, and a number of documentation updates.

Why This Release Matters​

Whether you're looking to backup and restore entire registries, publish multi-architecture bundles, or integrate ORAS into CI/CD pipelines, v1.3.0 brings the tools and the end-to-end artifact management solutions you need.

• Platform teams gain robust disaster recovery and migration tooling.
• DevOps engineers get the multi-arch flexibility needed for heterogeneous infrastructure.
• CI/CD and platform builders enjoy structured data outputs for reliable, scriptable workflows.
• Maintainers ship safer, cleaner, and more future-proof artifact workflows.

There are a few bug fixes and a deprecated feature in this release. For a concrete changelog, please see the ORAS v1.3.0 Release Notes.

Thanks to All Contributors​

Thanks to our existing maintainers @Wwwsylvia, @TerryHowe, @FeynmanZhou, @shizhMSFT, @sabre1041, @sajayantony, @qweeah who contributed to ORAS v1.3.0 and new contributors 🎉 @bcho, @njucjc, @nmiyake, @mauriciovasquezbernal, @Horiodino, @chrisguitarguy, @kysucix, @RohanMishra315, @apparentlymart, @tanyabhatnagar, @amazingfate 🚀.

You can follow the installation guidance to install ORAS v1.3.0 and try it out for yourself. End user feedback is essential in any open source project. If you run into issues or have any suggestions, please open an issue. To engage with the community, feel free to join the Slack channel in CNCF and find us in the oras channel.

This release includes new features, critical improvements, and bug fixes as we fine-tune ORAS for the upcoming stable release. Let’s dive into what’s new!

✨ What's New?​

OCI referrers is to associate additional artifacts with a container image without modifying the original image itself. Referrers are useful for software supply chain security, metadata enrichment, and artifact management.

oras discover provides structured output to show OCI referrers of a manifest in a registry or an OCI image layout. Previously, oras discover only shows direct referrers with limited metadata. Since this release, the output of oras discover has been enriched with showing all referrers recursively in all formatted outputs (tree, JSON, go-template) with annotations displayed by default. The subject manifest details is added to oras discover JSON output. It provides an informative output and ensures data consistency of different data formats in the output.

The tree view has better readability with colored-code visual effect on console as the screenshot shows below.

In addition, oras introduces an experimental --depth flag for oras discover, allowing users to specify the maximum depth of referrers in the formatted output. It avoids throttling or performance issues when a subject image has a complex referrer graph. For example, users can list the direct referrers of a subject image by specifying --depth 1 as the screenshot below.

Breaking Changes and Deprecation You Should Know​

• The global flag --no-tty flag has been removed, now available only for oras commands that need TTY behavior, improves consistency across commands.
• The property manifests has been renamed to referrers in the JSON output of oras discover
• The table output format is deprecated for oras discover

A sample output of oras discover in JSON format:

oras discover ghcr.io/kyverno/test-verify-image:signed --format json

{
  "reference": "ghcr.io/kyverno/test-verify-image@sha256:b31bfb4d0213f254d361e0079deaaebefa4f82ba7aa76ef82e90b4935ad5b105",
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "digest": "sha256:b31bfb4d0213f254d361e0079deaaebefa4f82ba7aa76ef82e90b4935ad5b105",
  "size": 938,
  "referrers": [
    {
      "reference": "ghcr.io/kyverno/test-verify-image@sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:7f870420d92765b42cec0f71ee8e25bf39b692f64d95d6f6607e9e6e54300265",
      "size": 738,
      "annotations": {
        "io.cncf.notary.x509chain.thumbprint#S256": "[\"da1f2d7d648dfacc7ebd59f98a9f35c753c331d80ca4280bb94060f4af4a5357\"]",
        "org.opencontainers.image.created": "2023-05-22T21:45:06Z"
      },
      "artifactType": "application/vnd.cncf.notary.signature"
    },
    {
      "reference": "ghcr.io/kyverno/test-verify-image@sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:f89cb7a0748c63a674d157ca84d725ff3ac09cc2d4aee9d0ec4315e0fe92a5fd",
      "size": 699,
      "annotations": {
        "org.opencontainers.image.created": "2023-05-25T16:13:11Z"
      },
      "artifactType": "vulnerability-scan",
      "referrers": [
        {
          "reference": "ghcr.io/kyverno/test-verify-image@sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3",
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:ec45844601244aa08ac750f44def3fd48ddacb736d26b83dde9f5d8ac646c2f3",
          "size": 728,
          "annotations": {
            "io.cncf.notary.x509chain.thumbprint#S256": "[\"da1f2d7d648dfacc7ebd59f98a9f35c753c331d80ca4280bb94060f4af4a5357\"]",
            "org.opencontainers.image.created": "2023-05-25T16:19:29Z"
          },
          "artifactType": "application/vnd.cncf.notary.signature"
        }
      ]
    },
    {
      "reference": "ghcr.io/kyverno/test-verify-image@sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:8cad9bd6de426683424a204697dd48b55abcd6bb6b4930ad9d8ade99ae165414",
      "size": 695,
      "annotations": {
        "org.opencontainers.image.created": "2023-05-25T16:17:41Z"
      },
      "artifactType": "sbom/cyclone-dx",
      "referrers": [
        {
          "reference": "ghcr.io/kyverno/test-verify-image@sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322",
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:61f3e42f017b72f4277c78a7a42ff2ad8f872811324cd984830dfaeb4030c322",
          "size": 728,
          "annotations": {
            "io.cncf.notary.x509chain.thumbprint#S256": "[\"da1f2d7d648dfacc7ebd59f98a9f35c753c331d80ca4280bb94060f4af4a5357\"]",
            "org.opencontainers.image.created": "2023-05-25T16:20:01Z"
          },
          "artifactType": "application/vnd.cncf.notary.signature"
        }
      ]
    },
    {
      "reference": "ghcr.io/kyverno/test-verify-image@sha256:aa886b475b431a37baa0e803765a9212f0accece0b82a131ebafd43ea78fa1f8",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:aa886b475b431a37baa0e803765a9212f0accece0b82a131ebafd43ea78fa1f8",
      "size": 681,
      "annotations": {
        "org.opencontainers.artifact.description": "CycloneDX JSON SBOM"
      },
      "artifactType": "application/vnd.cyclonedx+json",
      "referrers": [
        {
          "reference": "ghcr.io/kyverno/test-verify-image@sha256:00c5f96577878d79b545d424884886c37e270fac5996f17330d77a01a96801eb",
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:00c5f96577878d79b545d424884886c37e270fac5996f17330d77a01a96801eb",
          "size": 728,
          "annotations": {
            "io.cncf.notary.x509chain.thumbprint#S256": "[\"da1f2d7d648dfacc7ebd59f98a9f35c753c331d80ca4280bb94060f4af4a5357\"]",
            "org.opencontainers.image.created": "2023-07-10T16:55:36Z"
          },
          "artifactType": "application/vnd.cncf.notary.signature"
        },
        {
          "reference": "ghcr.io/kyverno/test-verify-image@sha256:f3dc4687f5654ea8c2bc8da4e831d22a067298e8651fb59d55565dee58e94e2d",
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:f3dc4687f5654ea8c2bc8da4e831d22a067298e8651fb59d55565dee58e94e2d",
          "size": 728,
          "annotations": {
            "io.cncf.notary.x509chain.thumbprint#S256": "[\"da1f2d7d648dfacc7ebd59f98a9f35c753c331d80ca4280bb94060f4af4a5357\"]",
            "org.opencontainers.image.created": "2023-07-10T16:56:36Z"
          },
          "artifactType": "application/vnd.cncf.notary.signature"
        }
      ]
    },
    ...

There are a few bug fixes and a deprecated feature in this release. For a concrete changelog, please see ORAS CLI v1.3.0-beta.3 Release Notes.

Join the ORAS community​

You can follow this installation guidance to install ORAS v1.3.0-beta.3 and have a try. Feedback is crucial at this stage. If you run into issues or have suggestions, please open an issue. Join the Slack channel in CNCF and find us at oras channel.

What's new in ORAS v1.2.0​

OCI Spec v1.1.0 support​

ORAS CLI v1.2.0 and ORAS-go v2.5.0 are now compliant with OCI image-spec v1.1.0 and distribution-spec v1.1.0. With OCI Spec v1.1.0 implemented by more and more OCI registries and officially supported in the ORAS client side, these major capabilities are officially enabled for users:

• Able to create, store, and distribute non-container artifacts, such as Helm Chart, Kubernetes manifest file, See OCI Artifact concept for details.
• Able to establish relationships between different artifacts. This allows users to associate the supply chain artifacts like SBOM, signature, vulnerability scanning report with the image. See The Art of Associating Artifacts for details.
• Able to discover and query artifact relationships, able to distribute a graph of artifacts across registries. See Listing Referrers concept for details.

Formatted output​

ORAS CLI has very basic output to show command operation result to human. For machine processing, especially in automation scenarios like scripting and CI/CD pipelines, developers may want to perform batch operations and chain different commands with ORAS, as well as filtering, modifying, and sorting objects based on the ORAS outputs. Developers expect that ORAS output can be emitted as machine-readable text, so that it can be used to perform further data manipulation.

With formatted output support in ORAS v1.2.0, it enables users to use the --format to format metadata output into structured data (e.g. JSON) and optionally use the --template with the Go template to manipulate the output data.

For example, push a file and two tags to a repository and show the descriptor of the image manifest in pretty JSON format:

oras push $REGISTRY/$REPO:$TAG1,$TAG2 sbom.spdx vul-scan.json --format json 

{
  "reference": "$REGISTRY/$REPO@sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45",
  "size": 820,
  "annotations": {
    "org.opencontainers.image.created": "2023-12-15T09:41:54Z"
  },
  "artifactType": "json/example",
  "referenceByTags": [
    "$REGISTRY/$REPO:$TAG1",
    "$REGISTRY/$REPO:$TAG2"
  ]
}

If you want to filter out the value of reference and media type of the pushed artifact in the standard output, use Go template functions as follows:

oras push $REGISTRY/$REPO:$TAG1,$TAG2 sbom.spdx vul-scan.json --format go-template='{{.reference}}, {{.mediaType}}'

$REGISTRY/$REPO@sha256:4a5b8c83d153f52afdfcb422db56c2349aae3bd5ecf8338a58353b5eb6681c45, application/vnd.oci.image.manifest.v1+json

This feature is still in "Experimental" stage. We welcome feedback and contributions to make this feature more mature.

Progress output to show real-time status​

Keeping track of manifest content download and upload has never been more intuitive and informative. With the progress output, users can witness the real-time status of manifest content pulling, pushing, and transferring. This is really helpful and effective when pulling or pushing large-size content from or to the registry.

Other enhancements​

• Support X.509 mTLS authentication with OCI registries by introducing --cert-file and --key-file in several ORAS commands
• Support deletion of manifests and blobs in OCI image layout
• Introduce --platform to oras attach for better multi-arch attaching experience, which allows adding referrer artifact to a specific sub-platform
• Introduce oras resolve to get the digest of an artifact

In addition, the overall user experience and performance are also enhanced in this release:

• Reduce authentication request count for several ORAS commands and support blob mounting across repositories in the same registry for oras copy
• Improve error message based on ORAS CLI error handling guidance

There are a few bug fixes and a deprecated feature in this release. For a concrete changelog, please see ORAS CLI v1.2.0 Release Notes.

Use ORAS CLI in terminal, Docker container and CI/CD pipelines​

ORAS installation binary is available on Winget, Homebrew, Snap, GitHub and Docker container image. It can be installed via one simple command. Please see the installation guide for your environment.

The ORAS GitHub Actions has been upgraded to ORAS CLI v1.2.0. ORAS CLI has also been integrated with the hosted runner machines (Ubuntu 22.04 and Ubuntu 20.04) on GitHub Actions and Azure DevOps as a preinstalled software. This delivers out-of-box experience to use ORAS in CI/CD pipelines.

What's next for ORAS​

ORAS CLI v1.3.0 will focus on verbose logs improvement for a better troubleshooting experience, image index for multi-arch image management, and annotating experience improvement. See the ORAS v1.3.0 milestone for details. Any feedback are welcome!

Join the ORAS community​

• Follow ORAS on X
• Join the Slack channel in CNCF and find us at oras channel

Setting up a centralized cloud OCI registry is sometimes too much for small scale tests and proof of concepts!
What if I told you there was a lightweight alternative?

Everything Should Be a File​

One of the great Unix philosophies is the concept of making everything a file. Modems, keyboards, printers, disk drives, serial interfaces, configuration, kernel parameters, IPC, everything and anything is a file that you can read() and/or write().

In a nutshell, this separates a many concerns to the file system layer instead of your program.
It allows, among other things, plugging stuff into any program without writing special integration code. That code was already written in the "driver" for that "device", so why repeat yourself in the program?

In General: programs write and read files
Making everything a file means that you can generally interface with every program.

Oras is EIAF Compatible​

oras has a --oci-layout

Instead of talking to an upstream service over http/https, oras can create the OCI artifact structure as files and directories.

Most (if not every) operation that can be performed on an upstream registry can also be performed locally as an OCI directory structure.

Cloud Object Storage is EIAF Compatible​

The file system is the foundation on which EIAF rests upon.
They are special components that convert media (CD, Tape, HDD, Controllers, etc.) into interface layers of which you can read/write files.

If you can mount it as a file system, you got EIAF.

Your preferred Cloud provider should have its own FUSE driver for their object storage offering, and if it doesn't, there is probably an alternative.

• Google Cloud Storage
• Azure Blob Storage
• AWS Simple Storage Service (Unofficial)

It is useful to think of Object Storage as key: data databases instead of the file systems they pretend to be.

Mounting one as a file system should be seen as "unintended functionality" and it breaks some assumptions programs make about file systems.

Example: Instant nanosecond retrieval times, turning into millisecond or even second long affairs.

Putting it together​

Now that we have the all the parts, it's just a matter of combining them!

For this tutorial we are using s3 with s3fs, but feel free to use a different provider and follow along!

Prerequisites​

• Install ORAS
• Install s3fs
• Obtain an AWS account and create a S3 bucket

Creating some test artifacts​

Let us first create some artifacts!

echo "Hello World!" > hello.txt
echo "Goodbye World!" > goodbye.txt

Mounting your s3 bucket​

Now we should mount our s3 bucket so that we can use it as an oci-layout target.
Checkout s3fs --help for the different ways you can authenticate, here we are using credential profiles.

mkdir s3
s3fs my-bucket s3 -o profile=MY_AWS_PROFILE

Using your new "registry"​

Pushing our newly created artifacts is as easy as:

oras push --oci-layout s3/hello:latest hello.txt:text/plain
oras push --oci-layout s3/goodbye:latest goodbye.txt:text/plain

Pulling them is just as simple!

rm hello.txt
rm goodbye.txt
oras pull --oci-layout s3/hello:latest
oras pull --oci-layout s3/goodbye:latest
cat hello.txt
cat goodbye.txt

Congratulations!​

Now you are running your own lightweight OCI registry on the cloud!

Caveats​

You can't delete yet!​

You can't delete your artifacts yet!

Currently¹ you can't delete your local oci-layout artifacts with oras manifest delete or oras blob delete

Normally it is the registry's responsibility to garbage collect blobs without any references, but in this case the cli does not have the functionality (yet).

It is still possible to just do rm -rf s3/my-repo, but that is probably not what you want to do.

Concurrency?​

Same concurrency rules of your chosen Object Store apply, generally last-write-wins. Please check your documentation

Using this trick in your application​

You can use this trick in your applications as well!

Instead of integrating in your application code (hard dependency, vendor lock-in, complicates your interface: "how do I pass in creds?") you instead mount the Object Store in the container and then "just use the file system" (transferable, simple, external, interfaceable)

There are some caveats to this approach and your application might leverage the capabilities of the Native Object Storage API extremely well, but if it's just a simple interaction, why complicate things?

Upgrading to Registry​

AWS Simple Storage Service (S3) to ZOT​

You can just point ZOT at the s3 bucket as it is already expecting an oci-layout

Other​

If you have a "normal" registry you'll need to export all your repos and their tags to that registry

Script​

NOTE: won't work with any repo containing a space or tab

ls -1 s3/ | xargs -P0 -n1 sh -c 'oras repo tags --oci-layout "s3/$1" | xargs -P0 -n1 -I{} oras copy --recursive --from-oci-layout "s3/$1:{}" "yourregistry/$1:{}"' _

There is no --oci-layout on oras repo ls, so we are substituting with: ls -1 s3/

Performance​

Goofys was the definitive champion utilizing the strengths of a local caching file system with the powers of a remote Object Store, it was the fastest in the cloud and local.

s3fs made a commendable effort and was faster than the native API on small objects, but started to lose performance on the bigger objects.

Findings​

tl:dr

Local performance:
Goofys made testing very difficult because it so effectively cached and reused objects, but installing it was a pain.
s3fs installed easily, but suffered around 512MiB, was bad at 1Gib, and was awful at 2Gib.

Cloud performance:
Amazing throughout.
Use Goofys.

Note: goofys is cheating!. It is a caching fs, so the numbers below are not an accurate representation of all use-cases.

Local​

Done inside WSL Ubuntu over WiFi.

This test was done over Wifi and was overall pretty slow especially with the bigger objects. Chunking the artifact did not lead to any substantial speed increases.

goofys isn't displayed, but you should try it out yourself!
It's asynchronous update and caching nature is so powerful and led to testing complications.

AWS​

Welp it's WAY faster over here!

goofys is an entire order of magnitude faster, but normalized around 2GiB.
s3fs was also faster than native up until about 2GiB.

Chunking the artifacts did not lead to any substantial speed increases... Except for goofys, which showed an upwards of 2x speed increase!

AWS2023 has removed the Extra Packages for Enterprise Linux (EPEL) repositories, so I used Debian instead. I used the apt distribution of s3fs and the go install of goofys.

Scripts used​

Feel free to modify and test how your flavors of fuse drivers stack up!

test-lib.sh​

#!/bin/bash

# bucket	- the s3 bucket
# s3dir		- the s3 mounted directory
# size		- bytes size. e.g. 15MiB, 1GiB, 2MB. should be valid for `head -c `
# count		- a integer
# datafile	- the file that contains the time information
# jtag		- a valid `junk` repo tag

# bucket dir
s3fsSetup() {
	dirname="$2"
	mkdir -p "$dirname"
	s3fs "$1" "$dirname" -o iam_role; #setup for cloud, you should modify for local testing
	echo "$dirname"
}

# bucket dir
goofysSetup() {
	dirname="$2"
	mkdir -p "$dirname"
	goofys "$1" "$dirname" #setup for cloud, you should modify for local testing
	echo "$dirname"
}

# s3dir
unmountS3() {
	umount "$1" &&
	  rmdir "$1"
}

# size
genSingle() {
	base64 < /dev/random | head -c "$1" > "${1}.junk"
	echo "${1}.junk"
}

# size count
genMulti() {
	seq 1 "$2" | xargs -n1 sh -c 'base64 < /dev/random | head -c "$1" > "${1}.${2}.junk"; echo "${1}.${2}.junk"' _ "$1"
}

# <(time)
time2line() {
	grep -Eo '[0-9]+m.+s' | tr '\n' '\t'
}

# s3dir size
singleBlobPush() {
	file=$(genSingle "$2")
	oras push --oci-layout "${1}/junk:${2}" "$file"
	rm "$file"
}

# s3dir size count
multiBlobPush() {
	files=$(genMulti "$2" "$3")
	echo "$files" | xargs -d'\n' -n"${3}" oras push --oci-layout "${1}/junk:${2}x${3}"
	echo "$files" | xargs -d'\n' rm -f
}

# datafile
resetDataFile() {
	printf '#%s\t%s\t%s\t%s\t%s\t\n' "type" "sizelabel" "realtime" "usertime" "systime" > "$1"
}

# s3dir jtag datafile
timeOrasPull() {
    exec 3>&1
	{ time oras pull --oci-layout "${1}/junk:${2}"; } 2>&1 1>&3 | printf '%s\t%s\t%s\n' "${1}" "${2}" "$(cat | time2line)" >> "$3"
	rm -f *.junk
}

# bucket jtag datafile
timeS3Junk() {
	exec 3>&1
	tmpdir=$(mktemp -d)
	{ time { aws s3 cp --recursive "s3://$1/junk/blobs/sha256/" "${tmpdir}/" 1>&1 2>&1 ; } ; } 2>&1 1>&3 | printf '%s\t%s\t%s\n' "aws-cli-s3" "${2}" "$(cat | time2line)" >> "$3"
	rm -rf "$tmpdir"
}

# s3dir
deleteJunkRepo() {
  rm -rf "$1/junk"
}

oci-test.sh​

Remember to set the AWS ENV Variables

#!/bin/bash

. test-lib.sh

set -u
set -e
set -o pipefail

: "${S3_BUCKET:="$1"}"

: "${DAT_FILE:="orastime.dat"}"
: "${S3FS_TDIR:="s3fs3"}"
: "${S3FS_TEST:="true"}"
: "${S3FS_S3_BUCKET:="$S3_BUCKET"}"
: "${GOOFYS_TDIR:="goofys3"}"
: "${GOOFYS_TEST:="true"}"
: "${GOOFYS_S3_BUCKET:="$S3_BUCKET"}"
: "${SINGLE_LIST:="8MiB 16MiB 32MiB 64MiB 128MiB 256MiB 512MiB 1GiB 2GiB"}"
: "${MULTI_LIST:="16MiBx8 64MiBx8 64MiBx16"}"

# time postmessage
sleepy() {
	echo "Sleeping for ${1}"
	sleep "$1"
	echo "$2"
}

# dir bucket datafile singlelist multilist
testit() {
	dir="$1"
	bucket="$2"
	datfile="$3"
	singlelist=($4)
	multilist=($5)
	
	# size
	trippleTimePull() {
		s="$1"
		echo "Pull 1 Starting..." &&
		timeOrasPull "$dir" "$s" "$datfile" && sleepy 1.3 "Pull 2 Starting..." &&
		timeOrasPull "$dir" "$s" "$datfile" && sleepy 1.3 "Pull 3 Starting..." &&
		timeOrasPull "$dir" "$s" "$datfile"
	}

	trippleTimeS3() {
		s="$1"
		echo "Copy 1 Starting..." &&
		timeS3Junk "$bucket" "$s" "$datfile" && sleepy 1.3 "Copy 2 Starting..." &&
		timeS3Junk "$bucket" "$s" "$datfile" && sleepy 1.3 "Copy 3 Starting..." &&
		timeS3Junk "$bucket" "$s" "$datfile"
	}

	echo "Starting: Oras S3 test on ${dir} into ${datfile}"

	for size in "${singlelist[@]}"
	do
		echo "Testing ${size}" &&
		singleBlobPush "$dir" "$size" &&
		trippleTimePull "$size" &&
		trippleTimeS3 "$size" && echo "Cleaning up..." &&
		deleteJunkRepo "$dir"
	done

	for sizexcount in "${multilist[@]}"
	do
		count="${sizexcount#*x}"
		size="${sizexcount%x*}"
		echo "Testing ${count} chunks of ${size}" &&
		multiBlobPush "$dir" "$size" "$count" &&
		trippleTimePull "$sizexcount" && 
		trippleTimeS3 "$sizexcount" && echo "Cleaning up..." &&
		deleteJunkRepo "$dir"
	done
}


if [ "S3FS-TDIR" = "s3fs" ]; then
	echo "IDFK Why but if you make the s3fs directory 's3fs' it breaks"  
	exit 1
fi

echo "Init Data File"
resetDataFile "$DAT_FILE"

if [ "$S3FS_TEST" = "true" ]; then
	echo "Setting up s3fs..."
	echo "$S3FS_S3_BUCKET"
	s3fsSetup "$S3FS_S3_BUCKET" "$S3FS_TDIR" 
	echo "Lets do this..."
	testit "$S3FS_TDIR" "$S3FS_S3_BUCKET" "$DAT_FILE" "$SINGLE_LIST" "$MULTI_LIST"
	echo "Unmounting..."
	unmountS3 "$S3FS_TDIR" 
fi

if [ "$GOOFYS_TEST" = "true" ]; then
	echo "Setting up goofys..."
	goofysSetup "$GOOFYS_S3_BUCKET" "$GOOFYS_TDIR"
	echo "Lets do this..."
	testit "$GOOFYS_TDIR" "$GOOFYS_S3_BUCKET" "$DAT_FILE" "$SINGLE_LIST" "$MULTI_LIST"
	echo "Unmounting..."
	unmountS3 "$GOOFYS_TDIR" 
fi

With a supermajority vote from the existing ORAS Organization Owners, we are excited to announce that Terry Howe and Andrew Block have been accepted as new ORAS Organization owners. In addition, Billy Zha and Feynman Zhou been accepted as ORAS subproject maintainers.

Terry has been actively contributing to ORAS since Dec 2022 and has been nominated to a sub-project maintainer on Feb 21. He raised 19 PRs to multiple ORAS repositories includes ORAS CLI, ORAS-go, and ORAS-www in the last quarter. He also reviewed Pull Request actively and left 126 comments in the same period.

Andrew worked frequently with the ORAS community members to build functionality into the v1 branch for which Helm makes use of as well as to provide test coverage and features to the current v2 main branch. He also saw how the capabilities produced by ORAS could be used outside of the Helm ecosystem, such as in Emporous (formerly called Universal Object Reference UOR) as a way to manage content within OCI registries. He also contributed to several features and bug fixes for ORAS-go.

Billy has contributed 103 PRs to the main branch and reviewed most the PRs of the ORAS CLI repository in the last 9 months. He also presented several demos and proposals in the ORAS community meeting.

Feynman has been actively contributing to the ORAS-www and ORAS CLI repositories in the past 10 months. He raised 11 Pull Requests and helped review several PRs in multiple repositories. He is also one of the meeting chair who organizes the ORAS community meeting in the last 10 months.

They have demonstrated their commitment and passion for the project. We are grateful for their contributions and leadership, and we look forward to working with them as owners of ORAS.

Thanks Emeritus Owners​

We also want to thank Avi Deitcher and Josh Dolitsky who have stepped down from their roles as owners of ORAS. Avi was one of the founding members of ORAS who helped shape its vision and direction. Josh was also one of the founding members of ORAS who instrumental in developing many features of ORAS, such as artifact reference types, push/pull options, etc. They have both moved to emeritus status but will continue to support ORAS as advisors. We appreciate their dedication and service to the project, and we wish them all the best for their future endeavors.

What's new in ORAS 0.15​

As ORAS has been adopted by more and more OCI implementors and registry vendors, we have seen increased community requirements in providing fine-grained capabilities to alter the content of OCI supply chain artifacts. ORAS 0.15 now supports granular blob and manifest operations for artifacts within the registry. Please see the Release Notes for details.

This blog post will demonstrate how to use ORAS CLI v0.15 to convert a Docker image stored in Docker Hub into an OCI image，then push it to the Distribution registry.

Prerequisites​

• Install ORAS 0.15.1
• Install Docker

Run a Distribution registry locally​

Run a local instance of the CNCF Distribution Registry, with ORAS Artifacts support (Note: OCI Artifact support is coming soon):

docker run -d -p 5000:5000 ghcr.io/oras-project/registry:v1.0.0-rc.4

Fetch and view the manifest of a sample Docker image​

Set the environment variable as below.

docker_digest="sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4"

Fetch the manifest and export it to a JSON file.

oras manifest fetch docker.io/library/hello-world@$docker_digest > docker.manifest.json

View the generated manifest file.

cat docker.manifest.json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 1469,
    "digest": "sha256:feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412"
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 2479,
      "digest": "sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54"
    }
  ]
}

Fetch and push a blob​

Per distribution-spec ,the blobs making up the object are uploaded first, and the manifest last. So we should fetch a blob from Docker Hub and push it to local registry, then upload the manifest.

Set the environment variable as below.

config_digest=$(cat docker.manifest.json | jq -r .config.digest)

Fetch a config blob to a local file from a sample Docker image:

oras blob fetch docker.io/library/hello-world@$config_digest --output config-blob.json

Then push this blob file to a new repository in a CNCF Distribution registry:

oras blob push localhost:5000/oras-distribution/hello-world config-blob.json

Similarly, fetch the layer blob and push it to the Distribution registry:

layer_digest=$(cat docker.manifest.json | jq -r .layers[].digest)

oras blob fetch docker.io/library/hello-world@$layer_digest --output layer-blob.json

oras blob push localhost:5000/oras-distribution/hello-world layer-blob.json

Push it to the sample repository with the blob file.

oras blob push localhost:5000/oras-distribution/hello-world layer-blob.json

Fetch and push a manifest​

Similar to blob operations above, fetch a manifest from a Docker image stored in Docker Hub and export it to a JSON file:

oras manifest fetch docker.io/library/hello-world@sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4 --output hello-manifest.json

Modify the manifest file hello-manifest.json from Docker to OCI type in each mediatype field of config and layer:

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "config": {
      "mediaType": "application/vnd.oci.image.config.v1+json",
      "size": 1469,
      "digest": "sha256:feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412"
   },
   "layers": [
      {
         "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
         "size": 2479,
         "digest": "sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54"
      }
   ]
}

Push the modified manifest file to the repository in the Distribution registry. It will also create a new repository automatically:

oras manifest push localhost:5000/oras-distribution/hello-world:latest hello-manifest.json

Validate the new image​

View the manifest of this Docker image from the Distribution registry, you will find all mediatype are changed to OCI type:

oras manifest fetch localhost:5000/oras-distribution/hello-world:latest

{
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "config": {
      "mediaType": "application/vnd.oci.image.config.v1+json",
      "size": 1469,
      "digest": "sha256:feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412"
   },
   "layers": [
      {
         "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
         "size": 2479,
         "digest": "sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54"
      }
   ]
}

Run and validate the new OCI image:

docker run localhost:5000/oras-distribution/hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

It turns out the conversion works.

Try multi-tagging and view the tags​

Tag the manifest with 'latest' to 'v1.0.0', 'v2.0.0':

oras tag localhost:5000/oras-distribution/hello-world:latest v1.0.0 v2.0.0

View the newly created tags in the sample repository:

oras repo tags localhost:5000/oras-distribution/hello-world
latest
v1.0.0
v2.0.0

Congratulations! You have experienced all new top-level commands in ORAS CLI 0.15.

What's next for ORAS​

Recently the OCI and ORAS maintainers submitted a proposal to unify the ORAS Artifact manifest with an OCI Artifact manifest (pr-934) and pr-335, to consolidate the specs. These changes provide adds new capabilities to OCI registries while maintaining the ability to function on registries that don't yet support the new Artifact manifest. This proposal originates from the ORAS artifact and has been accepted by the OCI group. The OCI group also cut a new release in the distribution-spec and image-spec supporting Reference Types, enabling a breadth of supply chain evidence to benefit from existing registries.

In ORAS CLI 0.16 and ORAS-go v2.0.0-rc.4, we'll add support for the OCI artifact spec will be the most significant plan and is targeted to be released at the end of October. You can find the migration proposal from this doc. See also the ORAS Roadmap for more detailed future plans.

Join the ORAS community​

The ORAS Project was accepted in June 2021 as a Cloud Native Computing Foundation (CNCF) Sandbox project. It is important that we hear from the community as we advance the artifact-spec capability; if you maintain or are implementing a container registry, we are particularly interested in your feedback. Working together, we can improve supply chain artifact security in the cloud native ecosystem.

• Follow ORAS on X
• Join the Slack channel in CNCF and find us at oras channel

Policies are rules expressed in YAML that not only afford meeting governance requirements, but also improve the security of Kubernetes workloads and clusters. Policy engines like OPA Gatekeeper, Kyverno or even the new Kubernetes's Validating Admission Policies feature help write and enforce such policies. Once the policies are written, however, how do we easily and securely share them with different projects and teams? How do we deploy them across the fleet of clusters? How do we evaluate them as early as possible in CI/CD pipelines?

In this blog post we will demonstrate how to bundle and share Gatekeeper policies as an OCI image using the ORAS command line client, how to evaluate any Kubernetes manifests against this OCI image with the gator command line client, and how to deploy this OCI image in Kubernetes clusters, in a GitOps way.

While we use Google Artifact Registry as the OCI registry for this example, you can use any registry supporting OCI artifacts. For the GitOps tool, we are using the OSS project: Config Sync, and you can also use it as part of the Anthos Config Management service or even use other GitOps tools supporting OCI images like FluxCD.

Create a Gatekeeper policy​

Let's create a Gatekeeper policy composed by one Constraint and one ConstraintTemplate that will be leveraged throughout this blog post.

In this example, we are making sure that any non-system namespaces is leveraging the Pod Security Admission feature to enforce the Pod Security Standards.

Create a dedicated folder for the associated files:

mkdir -p policies

Define the ConstraintTemplate to ensure that the Kubernetes resources contain specified labels:

cat <<EOF> policies/k8srequiredlabels.yaml
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              description: A list of labels and values the object must specify.
              items:
                properties:
                  allowedRegex:
                    description: If specified, a regular expression the annotation's
                      value must match. The value must contain at least one match
                      for the regular expression.
                    type: string
                  key:
                    description: The required label.
                    type: string
                type: object
              type: array
  targets:
    - target: admission.k8s.gatekeeper.sh
      rego: |
        package k8srequiredlabels
        violation[{"msg": msg, "details": {"missing_labels": missing}}] {
           provided := {label | input.review.object.metadata.labels[label]}
           required := {label | label := input.parameters.labels[_].key}
           missing := required - provided
           count(missing) > 0
           msg := sprintf("You must provide labels: %v for the %s: %s.", [missing, input.review.object.kind, input.review.object.metadata.name])
        }
        violation[{"msg": msg}] {
           value := input.review.object.metadata.labels[key]
           expected := input.parameters.labels[_]
           expected.key == key
           expected.allowedRegex != ""
           not re_match(expected.allowedRegex, value)
           msg := sprintf("Label %s: %s does not satisfy allowed regex: %s", [key, value, expected.allowedRegex])
        }
EOF

Define the associated Constraint for the Namespaces which must have the label pod-security.kubernetes.io/enforce as the key and either baseline or restricted as the value:

cat <<EOF> policies/ns-must-have-pss-label.yaml
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: ns-must-have-pss-label
spec:
  enforcementAction: deny
  match:
    kinds:
      - apiGroups:
        - ""
        kinds:
        - "Namespace"
    excludedNamespaces:
    - config-management-monitoring
    - config-management-system
    - gatekeeper-system
    - kube-node-lease
    - kube-public
    - kube-system
    - resource-group-system
  parameters:
    labels:
    - key: pod-security.kubernetes.io/enforce
      allowedRegex: (baseline|restricted)
EOF

Test this policy with local files​

Define a Namespace without the required label.

cat <<EOF > namespace-test.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: test
EOF

Let’s now locally test this Namespace against this policy with the gator CLI. This client makes it very convenient to test policies without any Kubernetes cluster!

gator test \
   --filename namespace-test.yaml \
   --filename policies/

Output similar to:

["ns-must-have-pss-label"] Message: "You must provide labels: {\"pod-security.kubernetes.io/enforce\"} for the Namespace: test."

Push the Gatekeeper policy as OCI image to Artifact Registry​

Assuming we already have a Google Artifact Registry repository ARTIFACT_REGISTRY_REPO_NAME in the region REGION and project PROJECT_ID.

Login to Artifact Registry:

gcloud auth configure-docker ${REGION}-docker.pkg.dev

Push the Gatekeeper policy as OCI image in Google Artifact Registry repository with ORAS:

oras push \
    ${REGION}-docker.pkg.dev/${PROJECT_ID}/${ARTIFACT_REGISTRY_REPO_NAME}/my-policies:1.0.0 \
    policies/

See that the OCI image has been uploaded in the Google Artifact Registry repository:

gcloud artifacts docker images list ${REGION}-docker.pkg.dev/${PROJECT_ID}/${ARTIFACT_REGISTRY_REPO_NAME}

Test this policy with the remote OCI image​

Let’s now locally test the Namespace created earlier against this policy as remote OCI image with the gator CLI. It is very convenient to share and evaluate your policies in different places (i.e. locally, during Continuous Integration pipelines, etc.)!

gator test \
   --filename namespace-test.yaml \
   --image ${REGION}-docker.pkg.dev/${PROJECT_ID}/${ARTIFACT_REGISTRY_REPO_NAME}/my-policies:1.0.0

Output similar to:

["ns-must-have-pss-label"] Message: "You must provide labels: {\"pod-security.kubernetes.io/enforce\"} for the Namespace: test."

Deploy this OCI image with Config Sync​

Assuming we already have a Kubernetes cluster where both Config Sync and Gatekeeper should be installed.

cat << EOF | kubectl apply -f -
apiVersion: configsync.gke.io/v1beta1
kind: RootSync
metadata:
  name: root-sync-policies
  namespace: config-management-system
spec:
  sourceFormat: unstructured
  sourceType: oci
  oci:
    image: ${REGION}-docker.pkg.dev/${PROJECT_ID}/${ARTIFACT_REGISTRY_REPO_NAME}/my-policies:1.0.0
    dir: .
    auth: none
EOF

Verify that the Constraint and ConstraintTemplate are actually deployed:

kubectl get constraints
kubectl get constrainttemplates

And voilà! That’s how easy it is to deploy Gatekeeper policies as OCI image in a GitOps way. Congrats!

Test this policy in the cluster​

Let’s now try to deploy the Namespace defined earlier:

kubectl apply -f namespace-test.yaml

Output similar to:

Error from server (Forbidden): error when creating "namespace-test.yaml": admission webhook "validation.gatekeeper.sh" denied the request: [ns-must-have-pss-label] You must provide labels: {"pod-security.kubernetes.io/enforce"} for the Namespace: test.

That's a wrap!​

In this article, we were able to package Gatekeeper policies as an OCI image and push it to an OCI Registry, thanks to ORAS. Then, we were able to leverage the new OCI image parameter of gator test command in order to shift-left the evaluation of these policies against any Kubernetes resources outside of an actual cluster. Finally, we deployed the Gatekeeper policies as OCI image in a GitOps way.

The continuous reconciliation of GitOps reconciles between the desired state, now stored in an OCI registry, with the actual state, running in Kubernetes. Gatekeeper policies as OCI images are now just seen like any container images for your Kubernetes clusters as they are pulled from OCI registries. This continuous reconciliation from OCI registries, not interacting with Git, has a lot of benefits in terms of scalability, performance and security as you will be able to configure very fine grained access to your OCI images, across the fleet of your clusters.

For a more complete tutorial illustrating this flow with Config Sync and Policy Controller as part of the Anthos Config Management service with Google Kubernetes Engine (GKE), you could check this other blog post out.

As you can see, ORAS has a long history and is still growing since it has an active community behind it. I was fortunate to join the ORAS community as a release manager in May 2022 and growing with the project this year. So I write this article to share the growth of the active community and project iteration that I witnessed in 2022. Let’s look back at what’s been happening this year and what we can expect in 2023 and beyond.

Moving fast with monthly release cadence​

ORAS provides an OCI registry client ORAS CLI with functional-rich command sets that users can benefit from, while developers can build their own clients on top of one of the ORAS client libraries including Golang and Python libraries.

We are following a monthly release cadence to ensure fast iteration so that we can get feedback and detect problems from the community and then fix them efficiently.

• ORAS CLI has 4 Minor releases and 2 Patch releases in 2022 and evolved into a powerful and easy-to-use OCI registry client. It supported the OCI artifact manifest and complied with the OCI v1.1 Specifications in the latest release
• ORAS-go has shifted the focus and feature development from v1 to v2 this year. It has 15 releases and recently announced the last RC (ORAS v2.0.0-RC.6) release. In contrast to v1, v2 brings more unified interfaces, notably fewer dependencies, higher test coverage, better documentation, etc. For those who are still relying on v1, don’t worry about its deprecation at this moment as v1 is still under maintenance. But it’s highly recommended to give v2 a try and you can expect a stable v2.0.0 to be available in Jan 2023.
• Similar to ORAS-go, ORAS-py is a Python SDK for ORAS. It was established and contributed by Vanessa starting in May 2022. Thanks to Vanessa, ORAS-py delivered 10 releases and a well-organized API and user documentation in 2022.

More active engagement in the community​

As some users might be aware, the ORAS project has an obvious growing trend in both user adoption and contributions starting from the middle of 2022. We are working to properly document the contribution and development process. Let’s see the remarkable statistics in 2022 as follows. You can also check out the detailed dashboards here.

• A total of 48 contributors submitted Pull Requests to ORAS repositories
• On average, there are around 764 contributions and 25 contributors per month and contained within 34 merged PRs per month
• These contributors come from 35 companies
• All Stars increased from 605 to 964, all Forks increased from 123 to 220 in the past year
• The total downloads of ORAS CLI are 600,368
• The number of new PRs has tripled in the last year
• Organized 17 public community meetings in 2022, see meeting notes

Adoption: Powering multiple industries and OSS communities​

ORAS CLI, ORAS Go, and Python SDK are designed to help users and developers manage OCI Distribution based artifacts. ORAS empowers the secure supply chain by enabling users to leverage the existing services they already have across their development to production environments.

Currently, the biggest cloud providers like Microsoft Azure, AWS, and Google Cloud are using ORAS to manage OCI artifacts in registries. ORAS Go SDK has been integrated and adopted by some industry-leading vendors and popular open-source projects. Here is part of known adopters till now:

• Amazon ECR
• Amazon EKS Anywhere
• Alibaba Cloud Service Mesh
• Artifact Hub
• Docker Hub
• GitHub
• Google Cloud
• Helm
• Singularity
• Microsoft Azure - ACR
• Notary v2
• KubeApps by VMware Tanzu
• VMware Application Catalog
• Emporous (Formerly UOR Framework) by Red Hat
• soci-snapshotter by AWS
• Zot

Contributions to upstream OCI​

Just a few years ago, there were no standards nor tooling for registries to natively store, discover, and pull a graph of OCI artifacts. To extend the registry’s role and form the industry standard, ORAS maintainers proposed a new artifact manifest type to describe and query relationships between objects stored in a registry, without mutating the existing content.

Initially, the reference types work was incubated under the CNCF ORAS Artifact manifest project. It has been contributed to the OCI Image and Distribution v1.1-RC specifications in Sep 2022. Now it is an industry standard and there are already a few early implementations, such as Azure Container Registry and Zot registry. After the OCI v1.1 specification is available, we expect more registry vendors start to support and implement it.

Diverse evangelism and advocacy​

Open-source contributions are not limited to coding. The non-code contributions like blogging, writing documentation, and technical sharing are also important for the ORAS community. It’s so good to see more and more users and contributors from different organizations sharing their use cases and best practices with ORAS toolings via blog posts or conference presentations this year. You can learn more about their experience from their articles and videos below.

Blogs​

• Notation signatures as ORAS and OCI artifacts by maxgio92 from Clastix
• Announcing Docker Hub OCI Artifacts Support by MILOS GAJDOS from Docker
• ORAS 0.14 and Future: Empower Container Secure Supply Chain by Feynman Zhou from Microsoft
• ORAS 0.15: A Fully Functional OCI Registry Client by Feynman Zhou and Yi Zha from Microsoft
• Deploy OCI artifacts and Helm charts the GitOps way with Config Sync from Google Cloud blogs
• Storing ABAP build artifacts in OCI registry by Lars Hvam from the SAP community blog

Presentations at conferences​

• Distributing Supply Chain Artifacts with OCI & ORAS Artifacts at KubeCon EU by Steve Lasker from Microsoft
• It’s Complicated: Relationships Between Objects In OCI Registries by Josh Dolitsky & Sajay Antony
• Secure Container Supply Chain with Notation, ORAS, and Ratify by Feynman Zhou from Microsoft
• Build and Deploy Cloud Native (OCI) Artifacts, the GitOps Way by Mathieu Benoit from Google
• Unleashing the Power of the Container Registry at DevConf.us by Andrew Block & Alex Flom

Looking forward: what’s next in 2023​

Looking forward to 2023, several exciting plans have already been identified:

• A stable release for ORAS CLI v1.0.0 and Go library v2.0.0, which are planned on Feb, 2023
• A new website that brings developer-friendly layout design, demos, and documentation
• Apply to become a CNCF Incubating project

Last but not least, special thanks go to the many outstanding contributors, community evangelists, adopters. We are also grateful to those who have incorporated ORAS in production and have been providing feedback to ensure ORAS is continuously improving. Let’s collaborate more on future milestones in 2023.

What's new in ORAS 0.14​

Please see the Release Notes for details.

Prior to ORAS CLI v0.14 release, the ORAS Go library, also released v2.0.0-rc.2 to support artifacts-spec v1.0.0-rc.2 and provides new functions to enable developers to build your own OCI client tool.

As cloud native development continues to grow, we have seen increased community interest in evolving registries to natively store, pull, copy, and discover a graph of supply chain artifacts. Artifact references are important for many use cases such as adding Software Bill of Materials (SBOM), security scan results, and container image signatures.

This blog will demonstrate how to use ORAS CLI v0.14 to copy an image from a public registry validated by Microsoft to a private registry, then attach an SBOM to it and discover the reference in a tree graph.

Note: we will use MAR (Microsoft Artifact Registry) and ACR (Azure Container Registry) for demonstration purpose only. There will be another blog posts to demonstrate how to use ORAS with Amazon ECR and Google GAR soon.

Install ORAS 0.14​

Install the latest release of ORAS on a Linux environment:

curl -LO https://github.com/oras-project/oras/releases/download/v0.14.1/oras_0.14.1_linux_amd64.tar.gz
mkdir -p oras-install/
tar -zxf oras_0.14.1_*.tar.gz -C oras-install/
mv oras-install/oras /usr/local/bin/
rm -rf oras_0.14.1_*.tar.gz oras-install/

Note: You can also refer to the installation guide for other different platforms.

Copy an image from Registry A to Registry B​

In this demo, we'll use ORAS to copy the container image from the public MAR registry to my private ACR registry. You can use your preferred container registry with ORAS.

oras copy mcr.microsoft.com/mmlspark/spark2.4:1.0.0 feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0

Using SBOM Tool to generate a SBOM​

An SBOM creates a machine-readable inventory of the software components that make up a given software product. Generating SBOM is a first step in Supply Chain Security.

You can use Docker SBOM or SBOM Tool to generate a SBOM for the target image.

SBOM Tool can be used to create SPDX 2.2 compatible SBOMs for any variety of artifacts. In this demo, we use SBOM Tool to create SPDX 2.2 compatible SBOM for the sample Spark image.

Install the SBOM Tool within a Linux environment:

curl -Lo sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x sbom-tool

Generate a SBOM for the Spark image stored in ACR:

sbom-tool generate -di feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0 \
  -b ./foo \
  -pn bar \
  -pv 0.1 \
  -bc ./foo \
  -ps MyCompany \
  -nsb http://mycompany.com

Then it will create a SBOM manifest.spdx.json in foo/_manifest/spdx_2.2.

Attach the SBOM to this image​

Next, let's attach the generate SBOM to this Spark image stored in ACR:

$ oras attach feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0 foo/_manifest/spdx_2.2/manifest.spdx.json --artifact-type example/sbom
Uploading 97a5dc071dd1 manifest.spdx.json
Uploaded  97a5dc071dd1 manifest.spdx.json
Attached to feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0
Digest: sha256:7592c8026675e463e7ced9b7ed369c2962b354a69b842423e8ctestdigest

View the graph of artifacts​

A linked graph of supply chain artifacts can be viewed through the ORAS discovery command:

$ oras discover feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0
Discovered 1 artifacts referencing feynmanacr.azurecr.io/mmlspark/spark2.4:1.0.0
Digest: sha256:28de427f1df8cdb99bc98536b489d75cc496a2d37c3b9266248etestdigest

Artifact Type   Digest
example/sbom    sha256:7592c8026675e463e7ced9b7ed369c2962b354a69b842423e8ctestdigest

ORAS Present and Future​

ORAS has been integrated and adopted by some industry-leading ISVs and projects, such as soci-snapshotter by AWS, KubeApps by VMware Tanzu, UOR Framework by Red Hat etc.

ORAS 0.15 and future milestones will provide more capabilities to easily manage OCI content and interact with registries. It will empower the container secure supply chain and focus on the following areas:

• Be able to manage repository, tag, manifest, and blob
• Support and migrate to OCI reference types
• Support push/pull artifacts from OCI Image Layout
• E2E testing

See the ORAS Roadmap for more details.

Join the ORAS community​

The ORAS Project was accepted in June 2021 as a Cloud Native Computing Foundation (CNCF) Sandbox project. It is important that we hear from the community as we advance the artifact-spec capability; if you maintain or are implementing a container registry, we are particularly interested in your feedback. Working together, we can improve supply chain artifact security in the cloud native ecosystem.

• Follow ORAS on X

• Join the Slack channel in CNCF and find us at oras channel

As cloud native development continues to grow, we have seen increased community interest in evolving registries to natively store, discover, and pull a graph of supply chain artifacts. Artifact references are important for many use cases such as adding Software Bill of Materials (SBOM), security scan results, and container image signing. With the release of the artifacts specification, end-user tooling can now implement discovery that makes it feasible to determine if there are any references attached to a container image, answering the key question: “What SBOMs or signatures are associated with this container image?”

The ORAS Project was accepted in June 2021 as a Cloud Native Computing Foundation (CNCF) Sandbox project. It is important that we hear from the community as we advance the artifact-spec capability; if you maintain or are implementing a container registry, we are particularly interested in your feedback. Working together, we can improve supply chain artifact security in the cloud native ecosystem.