Skip to main content

Air-Gapped Installation

For environments without access to ghcr.io, mirror all Helm charts and container images to an internal registry before installing. This page walks through the full mirroring process using ORAS.

Prerequisites​

  • ORAS CLI v1.2+
  • Helm v3.8.0+
  • Write access to your internal container registry

Mirror the Helm charts​

export REGISTRY=my-registry.corp.com

oras copy oci://ghcr.io/cosmonic/cosmonic-control:0.3.0 \
  oci://${REGISTRY}/cosmonic/cosmonic-control:0.3.0

oras copy oci://ghcr.io/cosmonic/cosmonic-control-hostgroup:0.3.0 \
  oci://${REGISTRY}/cosmonic/cosmonic-control-hostgroup:0.3.0

Mirror the container images​

The chart ships the following container images. Mirror each one to your private registry:

export VERSION=0.3.9  # match chart appVersion

# Core control plane
oras copy ghcr.io/cosmonic/runtime-operator:${VERSION} ${REGISTRY}/cosmonic/runtime-operator:${VERSION}
oras copy ghcr.io/cosmonic/nexus:${VERSION}            ${REGISTRY}/cosmonic/nexus:${VERSION}
oras copy ghcr.io/cosmonic/control/envoy:v1.35.2       ${REGISTRY}/cosmonic/control/envoy:v1.35.2

# Observability stack
oras copy ghcr.io/cosmonic/control/otel-collector-contrib:0.120.0  ${REGISTRY}/cosmonic/control/otel-collector-contrib:0.120.0
oras copy ghcr.io/cosmonic/control/prometheus:v3.3.1               ${REGISTRY}/cosmonic/control/prometheus:v3.3.1
oras copy ghcr.io/cosmonic/control/loki:3.5                        ${REGISTRY}/cosmonic/control/loki:3.5
oras copy ghcr.io/cosmonic/control/tempo:2.9.0                     ${REGISTRY}/cosmonic/control/tempo:2.9.0
oras copy ghcr.io/cosmonic/control/cosmo-perses:latest             ${REGISTRY}/cosmonic/control/cosmo-perses:latest
oras copy ghcr.io/cosmonic/control/kiwigrid-k8s-sidecar:1.30.10   ${REGISTRY}/cosmonic/control/kiwigrid-k8s-sidecar:1.30.10

# HostGroup
oras copy ghcr.io/cosmonic/control-host:${VERSION} ${REGISTRY}/cosmonic/control-host:${VERSION}
note

The observability image tags (envoy, otel-collector, prometheus, loki, tempo, perses, kiwigrid-k8s-sidecar) are pinned to specific versions independent of the chart appVersion. Check helm show values oci://ghcr.io/cosmonic/cosmonic-control --version 0.3.0 to confirm the exact tags for a given chart version before mirroring.

Configure registry credentials​

If your registry requires authentication, create the pull secret before installing:

kubectl create namespace cosmonic-system

kubectl create secret docker-registry registry-credentials \
  --docker-server=my-registry.corp.com \
  --docker-username=<username> \
  --docker-password=<password> \
  -n cosmonic-system

Install with mirrored images​

Several chart components set their own image registries explicitly, so a global override alone is not sufficient. Use the following values file to point every component at your private registry:

# air-gapped-values.yaml
global:
  image:
    registry: my-registry.corp.com
    pullSecrets:
      - name: registry-credentials

operator:
  image:
    registry: my-registry.corp.com
nexus:
  image:
    registry: my-registry.corp.com
envoy:
  image:
    registry: my-registry.corp.com
opentelemetryCollector:
  image:
    registry: my-registry.corp.com
prometheus:
  image:
    registry: my-registry.corp.com
loki:
  image:
    registry: my-registry.corp.com
tempo:
  image:
    registry: my-registry.corp.com
perses:
  image:
    registry: my-registry.corp.com
  provisioning:
    sidecar:
      registry: my-registry.corp.com

Install Cosmonic Control from your mirrored Helm chart:

helm install cosmonic-control oci://${REGISTRY}/cosmonic/cosmonic-control \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --create-namespace \
  --set envoy.service.type=LoadBalancer \
  -f air-gapped-values.yaml

Install the HostGroup from your mirrored chart:

helm install hostgroup oci://${REGISTRY}/cosmonic/cosmonic-control-hostgroup \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --set image.repository=${REGISTRY}/cosmonic/control-host \
  --set "image.pullSecrets[0].name=registry-credentials"

Wait for all components to be ready:

kubectl rollout status deploy -l app.kubernetes.io/instance=cosmonic-control -n cosmonic-system
kubectl rollout status deploy -l app.kubernetes.io/instance=hostgroup -n cosmonic-system