Wardengate

Install

Offline install

Wardengate supports fully air-gapped installs. A single signed release bundle contains every image, the Helm chart, the wgctl binaries, and a manifest with SHA-256 digests. You move the bundle across the airgap, load it into a local registry, and install from there.

What you need on each side

  • An internet-connected host with curl, gpg, and roughly 4 GB of free disk
  • A transfer medium — a removable drive, a one-way diode, an approved file drop — sized for a release bundle of ~1.8 GB
  • An internal container registry the air-gapped cluster can pull from (Harbor, Artifactory, ECR replica, distribution)
  • The air-gapped cluster with kubectl and helm, or a Docker host for the single-container path
  • An offline license bundle from your account manager, signed by the Wardengate release key

Download the release bundle

Release artifacts live at releases.wardengate.io. Each bundle is a gzipped tarball alongside a detached GPG signature.

VERSION=2.4.1
curl -fLO https://releases.wardengate.io/${VERSION}/wardengate-${VERSION}.tar.gz
curl -fLO https://releases.wardengate.io/${VERSION}/wardengate-${VERSION}.tar.gz.asc
curl -fLO https://releases.wardengate.io/release-key.asc

gpg --import release-key.asc
gpg --verify wardengate-${VERSION}.tar.gz.asc wardengate-${VERSION}.tar.gz

Do not proceed if verification fails — the bundle is the entire trust root for the install, and a failed signature check means the file either got corrupted in transit or is not genuine.

Bundle contents

Extract the tarball and inspect it. Layout is stable across releases:

tar -xzf wardengate-${VERSION}.tar.gz
ls wardengate-${VERSION}/

# manifest.json         digests + image list
# images/               OCI image tarballs
# charts/               wardengate-*.tgz helm chart
# bin/                  wgctl for linux/amd64, linux/arm64, darwin/arm64
# docs/                 offline copy of the site

Move the bundle across the airgap

Transfer the single tarball plus its signature. Do not extract on the connected side and ship individual files — the manifest is signed over the full bundle. Re-verify on the isolated side with the same GPG key.

Load images into your registry

Every image is shipped as an OCI tarball under images/. Load them into the local Docker daemon, retag against your registry, then push.

REGISTRY=registry.internal.example/wardengate
cd wardengate-${VERSION}

for f in images/*.tar; do
  docker load -i "$f"
done

# retag and push
jq -r '.images[] | "\(.name) \(.tag)"' manifest.json | while read name tag; do
  docker tag  "wardengate/${name}:${tag}" "${REGISTRY}/${name}:${tag}"
  docker push                              "${REGISTRY}/${name}:${tag}"
done

If your registry needs a pull secret, create it ahead of time in the target namespace and reference it via imagePullSecrets in the chart values.

Install the chart with overrides

Instead of helm repo add, install directly from the chart tarball in the bundle. Override imageRegistry so every image is pulled from your mirror.

helm upgrade --install wardengate \
  wardengate-${VERSION}/charts/wardengate-*.tgz \
  --namespace wardengate --create-namespace \
  --values values.yaml \
  --set global.imageRegistry=registry.internal.example/wardengate \
  --set global.imagePullSecrets[0].name=registry-pull

The global.imageRegistry override rewrites the registry portion of every image reference in the chart — control plane, migrate job, gateway, and agent — so you only have to pin it once.

Docker-only air-gapped install

If you run Wardengate from Docker instead of Kubernetes, load the server image locally and run it with an explicit tag — no registry push needed.

docker load -i wardengate-${VERSION}/images/server.tar
docker images | grep wardengate/server

docker run -d --name wardengate ... wardengate/server:${VERSION}

Offline license activation

Online deployments exchange a heartbeat with the licensing service; offline deployments skip that and install a signed license bundle instead. Request one from your account manager with the machine ID printed by a fresh install.

# get the machine ID from a running instance
wgctl license machine-id

# apply the signed bundle you received back
wgctl license activate --file wardengate-offline.lic --offline

# verify
wgctl license status
# Plan:        enterprise
# Seats:       250
# Expires:     2027-01-15
# Mode:        offline (signed)

License bundles are bound to a machine ID and a version range. Renewals are a new bundle, applied with the same wgctl license activate command.

Recommended layout for air-gapped ops

  • Keep every release bundle you have ever installed in an internal artifact store — you will need previous versions for rollbacks
  • Mirror the release-key.asc to your internal trust store so operators do not have to re-fetch it each time
  • Keep a record of applied license bundles alongside your infrastructure state, not just in the control plane database
  • Test upgrades in a mirrored staging cluster before carrying a bundle to production
  • Automate the image re-push step in whatever pipeline moves artifacts across the diode

Related