Air-Gapped Installation

This guide explains how to install Kedify in air-gapped or network-restricted Kubernetes clusters.

In this setup, cluster nodes cannot pull images directly from public registries such as ghcr.io or quay.io. You must first mirror all required images into your private registry and then configure Kedify Helm values to use the mirrored locations.

For the standard online installation, refer to Helm Installation.

Prerequisites

• A running Kubernetes cluster (for example EKS, GKE, AKS, OpenShift, or on-prem Kubernetes)
• Access to a private container registry reachable from your cluster nodes
• kubectl configured for your cluster
• helm installed
• docker (with buildx) or another OCI-compatible image tool
• A Kedify account with Organization ID and API key

Required Images

Mirror every Kedify and dependency image to your private registry. Pin the mirrored copies by digest for deterministic deployments.

Generate required-images.txt from the current Kedify Helm chart before entering the restricted environment:

helm repo add kedifykeda https://kedify.github.io/charts
helm repo update

helm template kedify-agent kedifykeda/kedify-agent \
  --version v0.7.1 \
  --namespace keda \
  --include-crds \
  --set keda.enabled=true \
  --set keda-add-ons-http.enabled=true \
  --set otel-add-on.enabled=true \
  --set kedify-predictor.enabled=true \
  | awk '$1 == "image:" {gsub(/"/, "", $2); print $2}' \
  | tr -d "'" \
  | sort -u > required-images.txt

cat required-images.txt

Mirror Images to Your Private Registry

The example below mirrors images to registry.internal.example.com. Adjust the registry host and target paths to match your environment.

REGISTRY="registry.internal.example.com"

while read -r IMAGE; do
  [ -z "$IMAGE" ] && continue

  TARGET="$REGISTRY/${IMAGE#*/}"

  docker pull "$IMAGE"
  docker tag "$IMAGE" "$TARGET"
  docker push "$TARGET"
done < required-images.txt

Configure Helm Values for Air-Gapped Registry

Create air-gapped-values.yaml and override image repositories to point to your mirrored registry.

agent:
  image:
    repository: registry.internal.example.com/kedify/agent
    tag: <agent-tag>
  kubectlImage:
    repository: registry.internal.example.com/kedify/kubectl
    tag: <kubectl-tag>

keda:
  image:
    keda:
      repository: registry.internal.example.com/kedify/keda-operator
      tag: <keda-operator-tag>
    metricsApiServer:
      repository: registry.internal.example.com/kedify/keda-metrics-apiserver
      tag: <keda-metrics-apiserver-tag>
    webhooks:
      repository: registry.internal.example.com/kedify/keda-admission-webhooks
      tag: <keda-webhooks-tag>

keda-add-ons-http:
  images:
    interceptor: registry.internal.example.com/kedify/http-add-on-interceptor:<http-interceptor-tag>
    scaler: registry.internal.example.com/kedify/http-add-on-scaler:<http-scaler-tag>
  kubectlImage:
    repository: registry.internal.example.com/kedify/kubectl
    tag: <kubectl-tag>

otel-add-on:
  image:
    repository: registry.internal.example.com/kedify/otel-add-on
    tag: <otel-add-on-tag>
  kubectlImage:
    repository: registry.internal.example.com/kedify/kubectl
    tag: <kubectl-tag>
  otelOperator:
    manager:
      image:
        repository: registry.internal.example.com/open-telemetry/opentelemetry-operator/opentelemetry-operator
        tag: <otel-operator-tag>
    kubeRBACProxy:
      image:
        repository: registry.internal.example.com/brancz/kube-rbac-proxy
        tag: <kube-rbac-proxy-tag>

kedify-predictor:
  image:
    repository: registry.internal.example.com/kedify/keda-prophet
    tag: <keda-prophet-tag>
  kedaPredictionController:
    image:
      repository: registry.internal.example.com/kedify/keda-prediction-controller
      tag: <keda-prediction-controller-tag>
  kubectlImage:
    repository: registry.internal.example.com/kedify/kubectl
    tag: <kubectl-tag>

If your registry requires authentication, configure imagePullSecrets for the relevant components and service accounts.

Install Kedify with Air-Gapped Values

Install Kedify with Helm and provide the image override values.

helm upgrade --install kedify-agent kedifykeda/kedify-agent \
  --namespace keda \
  --create-namespace \
  -f air-gapped-values.yaml

Validate the Installation

1. Check all pods are running:

kubectl get pods -n keda

2. Confirm images are pulled from your internal registry:

kubectl get pods -n keda -o jsonpath='{..image}' | tr ' ' '\n' | sort -u

3. Ensure there are no ImagePullBackOff or ErrImagePull states:

kubectl get pods -n keda
kubectl describe pod <pod-name> -n keda

Troubleshooting

• ImagePullBackOff from public registry: one or more image repositories were not overridden in Helm values.
• Pull authentication errors: verify registry credentials and imagePullSecrets configuration.
• TLS trust errors against internal registry: ensure cluster nodes trust the private registry CA certificate.
• Missing image in internal registry: confirm the exact digest-pinned image exists in the mirrored target repository.