Push and Pull Image Content¶

zot is an OCI image registry that allows you to store, manage, and share container images.

A zot registry can store and serve a variety of content, but the type of content may dictate your choice of a client tool.

For various content types, this document shows examples of using a third-party client tool that supports the content. The following table shows which content and client tools are demonstrated.

zot is compatible with kubernetes/cri-o using docker:// transport, which is the default.

In the following examples, the zot registry is located at localhost, using port number 5000.

Common tasks using skopeo for OCI images¶

skopeo is a command line client that performs various operations on OCI container images and image repositories.

For detailed information about using skopeo, see the skopeo man page.

Push an OCI image¶

This example pushes the latest container image for the busybox application to a zot registry.

$ skopeo --insecure-policy copy --dest-tls-verify=false --multi-arch=all \
   --format=oci docker://busybox:latest \
   docker://localhost:5000/busybox:latest

Pull an OCI image¶

This example pulls the latest container image for the busybox application and stores the image to a local OCI-layout directory (/oci/images).

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \
   docker://localhost:5000/busybox:latest \
   oci:/oci/images:busybox:latest

Pull an OCI image to a private docker registry¶

This example pulls the latest container image for the busybox application and stores the image to a local private docker registry.

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \
   docker://localhost:5000/busybox:latest \
   docker://localhost:5000/busybox:latest

Authentication¶

In these examples, authentication is disabled for the source and destination. You can enable authentication by changing the command line options as follows:

--src-tls-verify=true
--dest-tls-verify=true

You can also add credentials for authenticating with a source or destination repository:

--src-creds username:password
--dest-creds username:password

Common tasks using regclient for OCI images¶

regclient is a client interface that performs various operations on OCI container images and image repositories. The command line interface for regclient is regctl.

For detailed information about regctl commands, see the regctl Documentation.

Push an OCI image¶

This example pushes version 1.18 of golang to a tools repository within the registry.

$ regctl registry set --tls=disabled localhost:5000
$ regctl image copy ocidir://path/to/golang:1.18 localhost:5000/tools

Pull an OCI image¶

This example pulls version 1.18 of golang to a local OCI-layout directory.

$ regctl image copy localhost:5000/tools ocidir://path/to/golang:1.18

List all repositories in registry¶

This example list all repositories in the registry.

$ regctl repo ls localhost:5000

List tags¶

This example lists all tags in the tools repository within the registry.

$ regctl tag ls localhost:5000/tools

Pull and push manifest¶

This example pulls and pushes the manifest in the tools repository within the registry.

$ regctl manifest get localhost:5000/tools --format=raw-body
$ regctl manifest put localhost:5000/tools:1.0.0 \
--format oci --content-type application/vnd.oci.image.manifest.v1+json \
--format oci

Authentication¶

In the preceding examples, TLS authentication with the zot registry was disabled by the following command:

$ regctl registry set --tls=disabled localhost:5000

This command allows regctl to accept an HTTP response from the zot server. If TLS authentication is enabled on the zot registry server, you can omit this command from your regctl session.

Common tasks using oras for OCI artifacts¶

ORAS (OCI Registry As Storage) is a command line client for storing OCI artifacts on OCI repositories.

For detailed information about the oras commands in these examples, see the ORAS CLI documentation.

Push an artifact¶

This example pushes version 2 of an artifact file named hello-artifact to a zot registry.

$ oras push --plain-http localhost:5000/hello-artifact:v2 \
        --config config.json:application/vnd.acme.rocket.config.v1+json \
        artifact.txt:text/plain -d -v

Pull an artifact¶

This example pulls version 2 of an artifact file named hello-artifact from a zot registry.

$ oras pull --plain-http localhost:5000/hello-artifact:v2 -d -v

Attach a reference¶

$ echo '{"artifact": "localhost:5000/hello-artifact:v2", "signature": "pat hancock"}' > signature.json

$ oras push localhost:5000/hello-artifact \
  --artifact-type 'signature/example' \
  --subject localhost:5000/hello-artifact:v2 \
  ./signature.json:application/json

$ oras discover -o tree localhost:5000/hello-artifact:v2

Authentication¶

To authenticate with the zot server, log in at the start of your session using the following command:

$ oras login -u myUsername -p myPassword localhost:5000

You can also add credentials in the push or pull commands as in this example:

$ oras pull -u myUsername -p myPassword localhost:5000/hello-artifact:v2 -d -v

For additional authentication options, including interactive credential entry and disabling TLS, see the ORAS authentication documentation.

Common tasks using helm for helm charts¶

Helm is a package manager for Kubernetes. Among many other capabilities, helm can store and retrieve helm charts on OCI image repositories.

For detailed information about the helm commands in these examples, see Commands for working with registries in the helm documentation.

Push a helm chart¶

This example pushes version 1.2.3 of a zot helm chart to a zot-chart repository within the registry.

$ helm package path/to/helm-charts/charts/zot
$ helm push zot-1.2.3.tgz oci://localhost:5000/zot-chart

Pull a helm chart¶

This example pulls version 1.2.3 of a zot helm chart from a zot-chart repository within the registry.

$ helm pull oci://localhost:5000/zot-chart/zot --version 1.2.3

Authentication¶

To authenticate with the zot server, log in at the start of your session using the following command:

$ helm registry login -u myUsername localhost:5000

You will be prompted to manually enter a password.

Common tasks using crane for OCI images¶

crane is an open-source project that provides a command-line interface (CLI) for interacting with container registries, such as Docker Hub and Google Container Registry.

For detailed information about crane commands, see the crane Documentation.

Push an OCI image¶

This example pushes the latest container image for the alpine application to a registry.

$ crane --insecure push \
   oci/images/alpine:latest \
   localhost:5000/alpine:latest

Pull an OCI image¶

This example pulls the latest container image for the alpine application and stores the image to a local OCI-layout directory (/oci/images).

$ crane --insecure pull \
   --format oci \
   localhost:5000/alpine:latest \
   oci/images/alpine:latest

Copy an OCI image to a private docker registry¶

This example pulls the latest container image for the alpine application and stores the image to a local private docker registry.

$ crane --insecure copy \
   alpine:latest \
   localhost:5000/alpine:latest

List tags¶

This example lists all tags in the alpine image within the registry.

$ crane ls localhost:5000/alpine

Find the digest of an image¶

This example gets the digest of the alpine image within the registry.

$ crane digest localhost:5000/alpine:latest

Authentication¶

To authenticate with the registry server, log in at the start of your session using the following command:

$ crane auth login -u myUsername localhost:5000