Skip to content
Kedify Docs

Install from a private registry

This guide shows how to install Kedify with Helm when your cluster pulls images from a private registry.

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.

These image-mirroring steps also apply to a fully air-gapped installation. In that setup, the Agent runs without a connection to Kedify's hosted service, so the Dashboard and Insights are unavailable. A private registry alone does not disable the default hosted connection. For a fully disconnected setup, coordinate the Helm configuration with Kedify.

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
  • For a connected installation, 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:

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


helm template kedify-agent kedifykeda/kedify-agent \
  --version v0.8.3 \
  --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.

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 < required-images.txt

Configure Helm Values for a Private Registry

Create private-registry-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 with Private-Registry Values

Install Kedify with Helm and provide the image override values.

Terminal window
helm upgrade --install kedify-agent kedifykeda/kedify-agent \
  --namespace keda \
  --create-namespace \
  -f private-registry-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.

Configure and verify: Collect diagnostics for support

Reference: Versions · Helm values and component configuration

Related capabilities: Access, telemetry and connectivity boundaries