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.

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.