Skip to content
Kedify Docs

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 standard online installation options, refer to Dashboard Installation or Fleet 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 the following Kedify and dependency images to your private registry. All entries are digest-pinned for deterministic deployments.

Current source version: v0.5.5 (updated 2026-04-29) 

envoyproxy/envoy:v1.37.0@sha256:ee6db70f38ba0b95c10817484ecb7f8d71d3276b5e4dc7b52f12125806d5d419
ghcr.io/kedify/agent:v0.5.4@sha256:e1d3e93073a2b5b120e6d925c35dbdb75f5005ac738c69730a493612549ac19d
ghcr.io/kedify/http-add-on-interceptor:v0.11.1-2@sha256:4ab214997432fc6c1e786058f364741630f1b76f69cc5e03a5ee73812585959e
ghcr.io/kedify/http-add-on-scaler:v0.11.1-2@sha256:ed9188fd853175e7ae3916ea09023029190ef1e95ca95b4127cc1d0dd28e7f5a
ghcr.io/kedify/keda-admission-webhooks:v2.19.0-1@sha256:6074ddab809739a1c63a814e91dd0755db2a2a3378e625c4255cb77d155ed7c9
ghcr.io/kedify/keda-metrics-apiserver:v2.19.0-1@sha256:9b4eaca52f238a2faff0e80dfceb4b9474017fa283c9511da7a4790b5ee9b1a5
ghcr.io/kedify/keda-operator:v2.19.0-1@sha256:2ca1a2f03132cd40294f4ca69518aa355b20986592bf934e235aaa9339bf8db7
ghcr.io/kedify/keda-prediction-controller:v0.1.4@sha256:4d58486bcfa59e5a8fbf3b426d0b93a725578118ef8fef0011503edda8ad693d
ghcr.io/kedify/keda-prophet:v0.1.4@sha256:e8c256448484df0eb425b1bdef3716458ca6624f51d23a5f13bbbe6dae72cb5a
ghcr.io/kedify/kubectl:v1.33.1@sha256:2ea25099363a3f16a491fc2c5a30fff304a8bbd939c782f0f80b399e821084c3
ghcr.io/kedify/otel-add-on:v0.1.3@sha256:05d9eb41f52ee407b0637b69deed4ccab349c486a71f3f07337272752c7c7271
ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator:0.131.0@sha256:004e38c269fa37816e247d6b9196e339f7c65c5b6950309cd7b2d7d08c9cbdac
quay.io/brancz/kube-rbac-proxy:v0.19.1@sha256:ea7bdc09a4929c8cad2b84b06ea4455721e75d4b86aa3dddf41f29b4817db358

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.

Terminal window
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 <<'IMAGES'
envoyproxy/envoy:v1.37.0@sha256:ee6db70f38ba0b95c10817484ecb7f8d71d3276b5e4dc7b52f12125806d5d419
ghcr.io/kedify/agent:v0.5.4@sha256:e1d3e93073a2b5b120e6d925c35dbdb75f5005ac738c69730a493612549ac19d
ghcr.io/kedify/http-add-on-interceptor:v0.11.1-2@sha256:4ab214997432fc6c1e786058f364741630f1b76f69cc5e03a5ee73812585959e
ghcr.io/kedify/http-add-on-scaler:v0.11.1-2@sha256:ed9188fd853175e7ae3916ea09023029190ef1e95ca95b4127cc1d0dd28e7f5a
ghcr.io/kedify/keda-admission-webhooks:v2.19.0-1@sha256:6074ddab809739a1c63a814e91dd0755db2a2a3378e625c4255cb77d155ed7c9
ghcr.io/kedify/keda-metrics-apiserver:v2.19.0-1@sha256:9b4eaca52f238a2faff0e80dfceb4b9474017fa283c9511da7a4790b5ee9b1a5
ghcr.io/kedify/keda-operator:v2.19.0-1@sha256:2ca1a2f03132cd40294f4ca69518aa355b20986592bf934e235aaa9339bf8db7
ghcr.io/kedify/keda-prediction-controller:v0.1.4@sha256:4d58486bcfa59e5a8fbf3b426d0b93a725578118ef8fef0011503edda8ad693d
ghcr.io/kedify/keda-prophet:v0.1.4@sha256:e8c256448484df0eb425b1bdef3716458ca6624f51d23a5f13bbbe6dae72cb5a
ghcr.io/kedify/kubectl:v1.33.1@sha256:2ea25099363a3f16a491fc2c5a30fff304a8bbd939c782f0f80b399e821084c3
ghcr.io/kedify/otel-add-on:v0.1.3@sha256:05d9eb41f52ee407b0637b69deed4ccab349c486a71f3f07337272752c7c7271
ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator:0.131.0@sha256:004e38c269fa37816e247d6b9196e339f7c65c5b6950309cd7b2d7d08c9cbdac
quay.io/brancz/kube-rbac-proxy:v0.19.1@sha256:ea7bdc09a4929c8cad2b84b06ea4455721e75d4b86aa3dddf41f29b4817db358
IMAGES

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

Use the Kedify installation method you normally use (Dashboard, Fleet, or Helm), and provide the image override values.

Terminal window
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:

Terminal window
kubectl get pods -n keda

2. Confirm images are pulled from your internal registry:

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

3. Ensure there are no ImagePullBackOff or ErrImagePull states:

Terminal window
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.