Skip to main content

Air-Gapped Installation

This guide covers deploying Plexicus to clusters that have no outbound internet access, can only reach an internal container registry, or operate under strict egress policies. The Plexicus umbrella chart is fully air-gap capable — every external dependency is configurable and every optional integration that phones home can be disabled.

Chart support is mature; this guide is a starter

The umbrella chart fully supports air-gapped deployments via image mirroring and pluggable cert-manager issuers. The authoritative step-by-step mirror procedure ships inside the chart artifact under docs/image-registry.md (extract via helm pull --untar). This page is a high-level orientation for self-hosted customers — it summarises what to mirror, what to override, and points at the bundled material. Examples on this page assume chart 1.2.0 or later.

What Air-Gapped Means Here​

In this guide, "air-gapped" refers to any of the following deployment scenarios:

  • The Kubernetes cluster has no outbound internet access at all
  • The cluster can only reach an internal mirror registry, not the public Google Artifact Registry
  • Strict egress policies prevent reaching public OAuth providers, public ACME servers (Let's Encrypt), or external AI APIs

The Plexicus chart is designed to support these environments — every external dependency is configurable, and every optional integration that requires public internet access can be disabled.

High-Level Procedure​

  1. Mirror all images to your internal registry. Mirror the Plexicus chart OCI artifact and the 8 custom service container images (fastapi, worker, frontend, analysis-scheduler, codex-remedium, exporter, plexalyzer-code, plexalyzer-prov) plus the prerequisite infrastructure images (MongoDB, Redis, MinIO, PostgreSQL, Temporal — see step "Install Infrastructure Prerequisites" in the production install guide for the exact set, including any Bitnami init/sidecar images such as os-shell, mongodb-exporter, postgres-exporter, redis-exporter, redis-sentinel, kubectl, minio-object-browser). Full procedure: see docs/image-registry.md inside the chart artifact (extracted via helm pull --untar).

    Bitnami licensing change (August 2025)

    Bitnami moved their official chart images to a paid distribution. Free legacy images live under docker.io/bitnamilegacy/*. If you mirror these for air-gapped use, pull from bitnamilegacy/* and re-tag into your internal registry. Production deployments on amd64 Kubernetes can use these images directly.

  2. Mirror the mongo-seed-data init image separately. The MongoDB seed image (platform-standalone/mongo-seed-data) is an init container passed directly to the Bitnami subchart and is not covered by global.imageRegistry. It must be overridden explicitly under mongodb.initContainers. See docs/image-registry.md (bundled with the chart artifact) for the exact override block.

  3. Set global.imageRegistry in your values overlay. This single field redirects all 8 custom Plexicus service images:

    global:
      imageRegistry: "registry.internal.example.com/plexicus"
      imagePullSecrets:
        - name: my-registry-secret   # pull secret for your mirror
      security:
        allowInsecureImages: true     # required when mirror is non-Bitnami

    Leave global.imageRegistry empty to pull directly from Plexicus GAR (requires network access and the gar-secret pull secret). Setting it to your mirror removes the runtime dependency on Plexicus's GCP account.

  4. Replace Let's Encrypt with an internal CA. Override global.certManager.clusterIssuer to the name of your in-cluster issuer (for example, internal-ca-issuer). Provision the corresponding ClusterIssuer resource before running helm install.

    global:
      certManager:
        enabled: true
        clusterIssuer: "internal-ca-issuer"

  5. Disable integrations that require public internet. Leave the following keys empty or unset in your values overlay:

    IntegrationValues key(s) to leave empty
    Cloudflare Turnstileglobal.required.auth.turnstile.*
    Google OAuthglobal.required.auth.google.clientId/clientSecret
    Public OpenAIUse global.required.ai.* to point at a self-hosted or internal Azure OpenAI endpoint instead

  6. Optionally disable the dependency wait-loop. If your cluster DNS does not resolve the bundled service names before first boot, set:

    global:
      dependencies:
        waitEnabled: false

    Or override individual hosts:

    global:
      dependencies:
        redis:
          host: "my-redis.internal"
        temporal:
          host: "temporal.internal"

  7. Install with Helm (or ArgoCD). Pass your air-gapped values overlay alongside the standard customer overlay:

    helm install plexicus \
      oci://my-internal-registry.example.com/charts/plexicus \
      --version 1.2.0 \
      --namespace plexicus --create-namespace \
      -f values.yaml \
      -f values-override.yaml

Authoritative Reference​

For the complete mirror procedure — every image to mirror, exact tags, registry auth wiring, and the mongo-seed-data init container override — pull and extract the chart artifact and read the bundled docs/image-registry.md:

helm pull oci://europe-west3-docker.pkg.dev/plexicus-registry/charts/plexicus \
  --version $CHART_VERSION --untar
cat plexicus/docs/image-registry.md

This file is the source of truth, maintained alongside the chart and shipped with the version you installed. For environment-specific questions, contact engineering@plexicus.ai.

Verifying No Phone-Home​

After install, verify the cluster makes zero unexpected outbound calls. Suggested checks:

  • NetworkPolicy — chart 1.2.0 ships restrictive NetworkPolicy resources by default. Inspect them with: 
    kubectl get networkpolicy -n plexicus
  • Managed-SaaS integrations — confirm that any env vars referencing services Plexicus operates on the managed SaaS (commercial integrations) are unset in your values. The chart ships with these disabled by default; verify nothing was accidentally set. See the Configuration Reference for the policy.
  • Egress audit — use a transparent egress proxy or DNS sink to capture any outbound DNS queries during a 1-hour soak after install.

Need Help?​

For environment-specific guidance — custom CA chains, FIPS clusters, GovCloud, or air-gapped ArgoCD setups — contact engineering@plexicus.ai with your environment description.