quick-start.md

Getting Started with ORAS Artifacts

A quick-start for push, discover, pull

• Setup a few environment variables.

  export PORT=5000
  export REGISTRY=localhost:${PORT}
  export REPO=net-monitor
  export IMAGE=${REGISTRY}/${REPO}:v1

• Install the ORAS client
• Run a local instance of the CNCF Distribution Registry

  docker run -d -p ${PORT}:5000 ghcr.io/oras-project/registry:v0.0.3-alpha

• Build and Push $IMAGE

  docker build -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main
  docker push $IMAGE

• Push an SBoM

  echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json
  oras push $REGISTRY/$REPO \
      --artifact-type sbom/example \
      --subject $IMAGE \
      sbom.json:application/json
  
  echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "signature": "signed"}' > signature.json
  oras push $REGISTRY/$REPO \
      --artifact-type signature/example \
      --subject $IMAGE \
      signature.json:application/json

• List the tags, notice the additional metadata doesn't pollute the tag listing

  curl $REGISTRY/v2/$REPO/tags/list | jq

• Get referenced artifacts with the /referrers/ API

  DIGEST=$(oras discover $IMAGE -o json | jq -r .digest)
  curl $REGISTRY/oras/artifacts/v1/net-monitor/manifests/$DIGEST/referrers | jq

• Get a tree of references with oras discover

  oras discover -o tree $IMAGE

• Get a filtered list by artifactType

  curl "$REGISTRY/oras/artifacts/v1/net-monitor/manifests/$DIGEST/referrers?artifactType=sbom%2Fexample" | jq

• Get a filtered list with oras discover

  oras discover -o tree --artifact-type=sbom/example $IMAGE

• Pull a reference artifact by embedding oras discover

  oras pull -a \
      ${REGISTRY}/${REPO}@$( \
        oras discover  \
          -o json \
          --artifact-type sbom/example \
          $IMAGE | jq -r ".referrers[0].digest")

Further Reading

• Scenarios
• oras.artifact.manifest spec for persisting artifacts
• /referrers/ API spec for discovering artifacts