mindthegap

README

mindthegap provides utilities to manage air-gapped image bundles, both creating image bundles and seeding images from a bundle into an existing OCI registry.

Usage

Image bundles

Creating an image bundle

mindthegap create image-bundle --images-file <path/to/images.yaml> \
  --platform <platform> [--platform <platform> ...] \
  [--output-file <path/to/output.tar>]

See the example images.yaml for the structure of the images config file. You can also provide the images file in a simple file with an image per line, e.g.

nginx:1.21.5
test.registry2.io/test-image6:atag

Note that images from Docker Hub must be prefixed with docker.io and those "official" images must have the library namespace specified.

Platform can be specified multiple times. Supported platforms:

linux/amd64
linux/arm64
windows/amd64
windows/arm64

All images in the images config file must support all the requested platforms.

The output file will be a tarball that can be seeded into a registry, or that can be untarred and used as the storage directory for an OCI registry served via registry:2.

Pushing an image bundle

This command is deprecated - see Pushing a bundle

mindthegap push image-bundle --image-bundle <path/to/images.tar> \
  --to-registry <registry.address> \
  [--to-registry-insecure-skip-tls-verify]

All images in the image bundle tar file will be pushed to the target OCI registry.

Some registries (e.g. zot are strict about what media types they support. If you are pushing to a registry that only accepts OCI media types, then specify the --force-oci-media-types flag. This will internally convert any images that currently use Docker media types (application/vnd.docker.*) to OCI compatible media types (application/vnd.oci.*). Using the images via any container runtime does not change.

Serving an image bundle

This command is deprecated - see Serving a bundle

mindthegap serve image-bundle --image-bundle <path/to/images.tar> \
  [--listen-address <listen.address>] \
  [--listen-port <listen.port>]

Start an OCI registry serving the contents of the image bundle. Note that the OCI registry will be in read-only mode to reflect the source of the data being a static tarball so pushes to this registry will fail.

Importing an image bundle into containerd

mindthegap import image-bundle --image-bundle <path/to/images.tar> \
  [--containerd-namespace <containerd.namespace]

Import the images from the image bundle into containerd in the specified namespace. If --containerd-namespace is not specified, images will be imported into k8s.io namespace. This command requires ctr to be in the PATH.

Helm chart bundles

Creating a Helm chart bundle

mindthegap create helm-bundle --helm-charts-file <path/to/helm-charts.yaml> \
  [--output-file <path/to/output.tar>]

See the example helm-charts.yaml for the structure of the Helm charts config file.

The output file will be a tarball that can be seeded into a registry, or that can be untarred and used as the storage directory for an OCI registry served via registry:2.

Pushing a Helm chart bundle

This command is deprecated - see Pushing a bundle

mindthegap push helm-bundle --image-bundle <path/to/helm-charts.tar> \
  --to-registry <registry.address> \
  [--to-registry-insecure-skip-tls-verify]

All Helm charts in the bundle tar file will be pushed to the target OCI registry.

Serving a Helm chart bundle

This command is deprecated - see Serving a bundle

mindthegap serve helm-bundle --helm-bundle <path/to/helm-charts.tar> \
  [--listen-address <addr>] \
  [--list-port <port>] \
  [--tls-cert-file <path/to/cert/file> --tls-private-key-file <path/to/key/file>]

Start an OCI registry serving the contents of the image bundle. Note that the OCI registry will be in read-only mode to reflect the source of the data being a static tarball so pushes to this registry will fail.

Pushing a bundle (supports both image or Helm chart)

mindthegap push bundle --bundle <path/to/bundle.tar> \
  --to-registry <registry.address> \
  [--to-registry-insecure-skip-tls-verify]

All images in an image bundle tar file, or Helm charts in a chart bundle, will be pushed to the target OCI registry.

Serving a bundle (supports both image or Helm chart)

mindthegap serve bundle --bundle <path/to/bundle.tar> \
  [--listen-address <listen.address>] \
  [--listen-port <listen.port>]

Start an OCI registry serving the contents of the image bundle or Helm charts bundle. Note that the OCI registry will be in read-only mode to reflect the source of the data being a static tarball so pushes to this registry will fail.

How does it work?

mindthegap starts up an OCI registry and then uses crane as a library to copy the specified images for all specified platforms into the running registry. The resulting registry storage is then tarred up, resulting in a tarball of the specified images.

The resulting tarball can be loaded into a running OCI registry, or be used as the initial storage for running your own registry via Docker or in a Kubernetes cluster.

Contributing

This project uses https://www.jetpack.io/devbox/ to create a reproducible build environment. If you do not have devbox configured, then the following instructions should work for you. For further details, see https://www.jetpack.io/devbox/docs/installing_devbox/.

Integrate with direnv for automatic shell integration

Install direnv: https://direnv.net/docs/installation.html#from-system-packages.

Hook direnv into your shell if you haven't already: https://direnv.net/docs/hook.html.

Building the CLI

mindthegap uses task for running build tasks. task will be automatically available when the devbox environment is correctly set up.

Build the CLI using task build:snapshot that will output binary into ./dist/mindthegap_$(GOOS)_$(GOARCH)/mindthegap.