https://github.com/mesosphere/mindthegap
Easily create and use bundles for air-gapped environments
https://github.com/mesosphere/mindthegap
airgapped docker kubernetes oci-image restricted-environments
Last synced: 6 months ago
JSON representation
Easily create and use bundles for air-gapped environments
- Host: GitHub
- URL: https://github.com/mesosphere/mindthegap
- Owner: mesosphere
- License: apache-2.0
- Created: 2021-12-14T17:10:32.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-22T11:58:16.000Z (about 1 year ago)
- Last Synced: 2025-04-22T12:36:33.186Z (about 1 year ago)
- Topics: airgapped, docker, kubernetes, oci-image, restricted-environments
- Language: Go
- Homepage:
- Size: 3.31 MB
- Stars: 74
- Watchers: 19
- Forks: 11
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
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
### Creating a bundle
```shell
mindthegap create bundle \
[--images-file ] \
[--platform [--platform ...]] \
[--all-platforms] \
[--helm-charts-file ] \
[--oci-artifacts-file ] \
[--output-file ]
```
See the [example images.yaml](images-example.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.
```plain
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:
```plain
linux/amd64
linux/arm64
windows/amd64
windows/arm64
```
Alternatively use the `--all-platforms` flag to bundle images for all platforms specified in the origin manifests.
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`.
See the [example helm-charts.yaml](helm-example.yaml) for the structure of the
Helm charts config file. You can also provide the images file in a simple file with
a chart URL per line, e.g.
```plain
oci://ghcr.io/stefanprodan/charts/podinfo:6.1.0
```
It is also possible to include OCI artifacts that are not OCI images.
This is useful for bundling Flux kustomizations, Helm Charts directly from OCI
registries, and any arbitrary OCI artifacts. To include an OCI artifacts, specify
the `--oci-artifacts-file` path. The format of the provided file matches the
`--images-file` format. The `--platform` flag has no effect on OCI artifacts.
The OCI artifacts with image index are not supported.
### Pushing a bundle
```shell
mindthegap push bundle --bundle \
--to-registry \
[--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.
#### Existing tag behaviour
When pushing to a registry which could already contain tags that are included in the bundle, the behaviour can be
specified via the `--on-existing-tag` flag. The following strategies are available:
- `overwrite`: Overwrite the tag with the contents from the bundle (Default)
- `error`: Return an error if a matching tag already exists
- `skip`: Do not push the tag if it already exists
- `merge-with-retain`: Merge the image index from the bundle with the existing tag, retaining any platforms that already
exist in the registry
- `merge-with-overwrite`: Merge the image index from the bundle with the existing tag, overwriting any platforms that
already exist in the registry
### Serving a bundle
```shell
mindthegap serve bundle --bundle \
[--listen-address ] \
[--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.
### Importing an image bundle into containerd
```shell
mindthegap import image-bundle --image-bundle \
[--containerd-namespace 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
.
### Integrate with `direnv` for automatic shell integration
Install direnv: .
Hook direnv into your shell if you haven't already: .
## Building the CLI
`mindthegap` uses [`task`](https://taskfile.dev/) 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`.