# 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](https://docs.kedify.io/installation/helm/).

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:

```bash
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.

```bash
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.

```yaml
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.

```bash
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:

```bash
kubectl get pods -n keda
```

2. Confirm images are pulled from your internal registry:

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

3. Ensure there are no `ImagePullBackOff` or `ErrImagePull` states:

```bash
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.

## Related documentation

**Configure and verify:**[Collect diagnostics for support](https://docs.kedify.io/troubleshooting/collecting-kedify-configuration/)

**Reference:**[Versions](https://docs.kedify.io/getting-started/versions/) · [Helm values and component configuration](https://docs.kedify.io/reference/helm-values/)

**Related capabilities:**[Access, telemetry and connectivity boundaries](https://docs.kedify.io/security-and-compliance/access-and-data/)

---
Canonical: https://docs.kedify.io/installation/air-gapped/
Source: src/pages/installation/air-gapped.astro
Documentation index: https://docs.kedify.io/llms.txt