doytsujin / regclient

Docker and OCI Registry Client in Go and tooling using those libraries.

regclient

Client interface for the registry API. This includes regctl for a command line interface to manage registries.

regctl Features

• Ability to inspect repo tags, manifests, and image configs without downloading the full image.
• Ability to copy or retag an image without pulling it into docker. Layers are only pulled if you are copying between different registries and the target registry does not have the layers already.
• Ability to copy all platforms of a multi-platform image.
• Ability to import an image to a registry from a tar file (OCI or Docker formatted).
• Ability to export an image from a registry to a tar file (using a combined OCI and Docker format).
• Ability to delete an image manifest.
• Ability to delete a tag without removing the entire manifest.
• Uses docker registry logins and /etc/docker/certs.d by default to support private repositories and self signed registries.
• Shows current usage of Docker Hub's rate limit.

regsync features

• Ability to copy or retag an image without pulling it into docker. Layers are only pulled if you are copying between different registries and the target registry does not have the layers already.
• Ability to copy all platforms of a multi-platform image.
• Mirrors repositories or images based on a yaml configuration.
• Can use user's docker configuration for registry credentials.
• Ability to run on a cron schedule, one time synchronization, or only check for stale images.
• Ability to backup previous target image before overwriting.
• Ability to postpone mirror step when rate limit is below a threshold.
• Ability to mirror multiple images concurrently.

regbot features

• Runs user provided scripts based on a yaml configuration.
• Scripts are written in Lua and executed directly in Go.
• Can run on a cron schedule or a one time execution.
• Dry-run option can be used for testing.
• Built-in functions include:
  • Repository list
  • Tag list
  • Image manifest (either head or get, and optional resolving multi-platform reference)
  • Image config (this includes the creation time, labels, and other details shown in a docker image inspect)
  • Image ratelimit and a wait function to delay the script when ratelimit remaining is below a threshold
  • Image copy
  • Manifest delete
  • Tag delete

Development Status

This project is in active development, a few features are not complete. Unfinished or not yet started work includes:

• Ability to retry from a partial layer download.
• Documentation.
• Testing.

Building

git clone https://github.com/regclient/regclient.git
cd regclient
go build -o regctl ./cmd/regctl/

Downloading Binaries

Binaries are available on the releases page.

The latest release can be downloaded using curl (adjust "regctl" and "linux-amd64" for the desired command and your own platform):

curl -L https://github.com/regclient/regclient/releases/latest/download/regctl-linux-amd64 >regctl
chmod 755 regctl

Running as a Container

You can run regctl, regsync, and regbot in a container.

For regctl:

docker container run -it --rm --net host \
  -v regctl-conf:/home/appuser/.regctl/ \
  regclient/regctl:latest --help

For regsync:

docker container run -it --rm --net host \
  -v "$(pwd)/regsync.yml:/home/appuser/regsync.yml" \
  regclient/regsync:latest -c /home/appuser/regsync.yml check

For regbot:

docker container run -it --rm --net host \
  -v "$(pwd)/regbot.yml:/home/appuser/regbot.yml" \
  regclient/regbot:latest -c /home/appuser/regbot.yml once --dry-run

Or on Linux and Mac environments, you can run regctl as your own user and save configuration settings, use docker credentials, and use any docker certs:

docker container run -it --rm --net host \
  -u "$(id -u):$(id -g)" -e HOME -v $HOME:$HOME \
  -v /etc/docker/certs.d:/etc/docker/certs.d:ro \
  regclient/regctl:latest --help

And regctl can be packaged as a shell script with:

cat >regctl <<EOF
#!/bin/sh

docker container run -it --rm --net host \\
  -u "\$(id -u):\$(id -g)" -e HOME -v \$HOME:\$HOME \\
  -v /etc/docker/certs.d:/etc/docker/certs.d:ro \\
  regclient/regctl:latest "\$@"
EOF
chmod 755 regctl
./regctl --help

Installing as a Docker CLI Plugin

To install regctl as a docker CLI plugin:

make plugin-user # install for the current user
make plugin-host # install for all users on the host (requires sudo)

Once installed as a plugin, you can access it from the docker CLI:

$ docker regctl --help
Utility for accessing docker registries
More details at https://github.com/regclient/regclient

Usage:
  regctl <cmd> [flags]
  regctl [command]

Available Commands:
  help        Help about any command
  image       manage images
  layer       manage image layers/blobs
  registry    manage registries
  tag         manage tags
...

Usage

See the project documentation.

Comparison to Other Tools

Registry client API:

• containerd: containerd'd registry APIs focus more on pulling images than on a general purpose registry client API. This means various registry API calls are not provided.
• distribution/distribution: The distribution project is focused on the server side of the registry API. There are a few client API's, but they appear to be intended for internal use.

There are also a variety of registry command line tools available:

• genuinetools/img: img works on top of buildkit for image creation and management. Using this for a registry client means including lots of dependencies that many will not need.
• genuinetools/reg: reg is probably the closest match to this project. Some features included in regctl that aren't included in reg are the ability to inject self signed certs, store login credentials separate from docker, copy or retag images, and export images into a tar file.
• containers/skopeo: Because of RedHat's push to remove any docker solutions from their stack, their skopeo project wasn't considered when searching for a complement to docker's tooling.