Air-gap workflow

The three planes

1. 01
   Vendor side — Autonomize-run.

   This portal at downloads.genesis.autonomize.ai. Issues license keys, signs bundles with cosign using an Azure Key Vault HSM key (KMS-keyed, P-256), generates SBOM + HIPAA PDF, uploads to Azure Blob, registers a Release row in Postgres. Customer never reaches in here.

2. 02
   Gap-host (bastion) — one-way internet + kubectl.

   Customer-controlled bastion VM that can talk to downloads.genesis.autonomize.ai over HTTPS. Also has kubectl access to the cluster. Runs the genesis CLI to pull, verify, push images to your registry, and deploy — all from the same host. No separate "sneakernet only" box required.

   For SCIF / FedRAMP-High environments requiring formal separation-of-duties, a two-host split (internet-only gap-host + air-gapped deploy host) is supported; standard HIPAA / SOC2 customers use the single-bastion model.

3. 03
   Customer cluster — air-gapped VPC.

   Your VPC. Pods pull images from your private registry (genesis push-images relocated them there). No outbound calls to Autonomize after install. Opt-in heartbeat is aggregate-only and customer-controlled.

The pull → verify → push-images → deploy cycle

1. A
   Pull on the gap-host.

   Authenticate once with your license key, then pull both bundles for a release. Each pull writes {bundle}.tar.zst + .sig sidecar + cosign.pub + .sha256 manifest + the merged {bundle}.tar.zst.sbom.cdx.json + the per-image {bundle}.tar.zst.sboms.tar.gz tarball (input to genesis scan).

   genesis login                    # paste sk_yourorg_*
   genesis releases                 # list versions you're entitled to
   genesis pull <VERSION>           # downloads ops + platform bundles

2. B
   Verify signatures & scan for CVEs.

   cosign confirms the AzDO release pipeline signed each bundle; sha256 confirms bytes are intact. genesis verify wraps both. genesis scan extracts the per-image SBOM sidecar and runs trivy against each image's CycloneDX — exits non-zero on HIGH/CRITICAL findings so it gates CI cleanly.

   genesis verify ./genesis-ops-<VERSION>.tar.zst
   genesis verify ./genesis-platform-<VERSION>.tar.zst
   # Both must print: ✓ cosign verify OK · sha256 match
   
   genesis scan ./genesis-ops-<VERSION>.tar.zst        # HIGH+CRITICAL → exit 1
   genesis scan ./genesis-platform-<VERSION>.tar.zst   # add --no-fail for report-only

3. C
   Push images to your registry.

   This is the step that satisfies your CISO's image-provenance requirement. Every Genesis container image is relocated from the bundle into your registry. Your scanner then runs against your registry. When pods start, they pull from your registry — never from Autonomize infrastructure.

   Push before deploy Push both the ops and platform bundles now. If you push only the platform bundle, ops pods will fail to pull images during genesis deploy --bundle genesis-ops-*.

   REGISTRY=your-registry.example.com   # ECR / ACR / Harbor / GCR / Nexus
   
   genesis push-images --to ${REGISTRY} --bundle ./genesis-ops-<VERSION>.tar.zst
   genesis push-images --to ${REGISTRY} --bundle ./genesis-platform-<VERSION>.tar.zst
   
   # ◄─── run your CISO scanner against ${REGISTRY} here before continuing ───►

   For Azure ACR without Docker: authenticate with az acr login --name <registry> --expose-token and write to ~/.config/containers/auth.json. See the install guide step 6 for the exact snippet.

4. D
   Install ESO + apply ExternalSecret CRs before deploying.

   Two ExternalSecret CRs must exist in the genesis namespace before platform pods start. Apply them now — if they're missing, pods crash with CreateContainerConfigError immediately. The CRs depend on External Secrets Operator (ESO) and a ClusterSecretStore pointing at your vault — install both first if you don't already have them. Credentials stay in your cloud secret manager; ESO syncs them into K8s Secrets automatically.

   # D.1 — Install ESO (skip if already installed). Registers the
   # ExternalSecret + ClusterSecretStore CRDs. Must serve
   # external-secrets.io/v1 BEFORE preflight — its eso-version check
   # hard-FAILs when the CRD is absent.
   #
   # Air-gapped: install from your INTERNAL mirror or the
   # genesis-external-secrets subchart shipped in the platform bundle.
   # The public Helm repo below is NOT reachable air-gapped.
   helm upgrade --install external-secrets \
     oci://<your-registry>/charts/external-secrets --version 0.18.2 \
     -n external-secrets --create-namespace \
     --set installCRDs=true \
     --set image.repository=<your-registry>/external-secrets/external-secrets \
     --wait
   # Connected clusters only:
   #   helm repo add external-secrets https://charts.external-secrets.io && helm repo update
   #   helm upgrade --install external-secrets external-secrets/external-secrets \
   #     -n external-secrets --create-namespace --set installCRDs=true --wait
   
   # D.2 — Create a ClusterSecretStore pointing at your vault. Stub below
   # is Azure Key Vault + Workload Identity; substitute the AWS / Vault /
   # GCP variant from the secrets setup guide below.
   cat <<'YAML' | kubectl apply -f -
   apiVersion: external-secrets.io/v1
   kind: ClusterSecretStore
   metadata:
     name: customer-akv     # ← matches secretStoreRef.name in both ExternalSecret templates
   spec:
     provider:
       azurekv:
         authType: WorkloadIdentity
         vaultUrl: "https://YOUR-KEYVAULT.vault.azure.net"
         serviceAccountRef:
           name: external-secrets
           namespace: external-secrets
   YAML
   
   kubectl wait --for=condition=Ready clustersecretstore/customer-akv --timeout=60s
   
   # D.3 — Apply the two ExternalSecret CRs.
   kubectl create namespace genesis 2>/dev/null || true
   
   # Edit templates IN PLACE (secretStoreRef.name → customer-akv or your
   # ClusterSecretStore name; uncomment oidc-client-secret only when
   # auth_mode=client_secret), then apply from the repo root:
   kubectl apply -f docs/customer/templates/customer-genesis-secrets-externalsecret.yaml  # DB + OIDC secret refs
   kubectl apply -f docs/customer/templates/ai-studio-secrets-externalsecret.yaml         # full subchart env-var bundle
   
   # Wait for ESO to materialise both Secrets
   kubectl -n genesis get externalsecret -w
   # Status must show SecretSynced for both before continuing

   Ready-to-edit CR templates: customer-genesis-secrets-externalsecret.yaml · ai-studio-secrets-externalsecret.yaml. Full key list + AWS / Azure / GCP setup walkthrough: required-secrets.md.

5. E
   Bootstrap zarf & deploy the ops bundle.

   zarf init runs once per cluster lifetime. Then deploy the ops bundle — this installs the 5 CRDs, the deploy operator, and Genesis Bastion. The platform bundle cannot deploy without this step.

   # One-time per cluster: zarf bootstrap
   ZARF_VER=v0.76.0
   zarf init zarf-init-amd64-${ZARF_VER}.tar.zst --confirm
   kubectl -n zarf get secret zarf-state    # must exist before ops deploy
   
   # Deploy ops (images pull from your registry)
   genesis deploy \
     --bundle ./genesis-ops-<VERSION>.tar.zst \
     --registry ${REGISTRY} \
     -n genesis
   
   kubectl -n genesis get pods              # all pods must reach 1/1 Running

6. F
   Configure, preflight, deploy platform.

   Write the genesis-platform-config ConfigMap, run all 34 preflight checks, then deploy the platform bundle. All three steps use the CLI — no browser or port-forward required.

   # Configure: write ConfigMap to cluster + emit Helm values
   genesis configure \
     --from genesis.yaml \
     --save \
     --emit-helm-values /tmp/genesis-platform-values.yaml
   
   # Preflight: all 34 checks must PASS before platform install
   genesis preflight -n genesis
   # Exit 0 = all PASS. Any FAIL prints Vin Advisor advice inline.
   
   # Deploy platform (images pull from your registry)
   genesis deploy \
     --bundle ./genesis-platform-<VERSION>.tar.zst \
     --registry ${REGISTRY} \
     --values /tmp/genesis-platform-values.yaml \
     -n genesis
   
   # Verify
   genesis status -n genesis

   For the wizard-driven alternative (browser form for configuration + preflight), see the install guide wizard section. Steps A–E above are identical for both paths; the wizard handles step F only.

Frequently surprising things