Install Odigos Images from a Custom Docker Registry

Tagging and Pushing Images

Step 1: Set Environment Variables

First, export the VERSION, CUSTOM_DOCKER_REGISTRY, PLATFORM, and ODIGOS_TOKEN environment variables in your shell:

export VERSION=<YOUR-DESIRED-VERSION>
export CUSTOM_DOCKER_REGISTRY=<YOUR-CUSTOM-DOCKER-REGISTRY>
export PLATFORM=<YOUR-PLATFORM-ARCHITECTURE>
export ODIGOS_TOKEN=<YOUR-ONPREM-TOKEN>

Replace <YOUR-DESIRED-VERSION> with the version of the Odigos images you want to use, <YOUR-CUSTOM-DOCKER-REGISTRY> with the URL of your custom Docker registry, <YOUR-PLATFORM-ARCHITECTURE> with the platform architecture of the environment where you are deploying Odigos (linux/amd64, linux/arm64), and <YOUR-ONPREM-TOKEN> with your Odigos Enterprise on-prem token.

Step 2: Authenticate to the Enterprise Registry

Enterprise images are hosted on the private registry registry.odigos.io. Authenticate with your on-prem token before pulling. The username is always odigos; the password is your on-prem token. Choose the method that matches how you will pull images:

Docker
Podman
Local auth file
Kubernetes pull secret

echo "$ODIGOS_TOKEN" | docker login registry.odigos.io -u odigos --password-stdin

echo "$ODIGOS_TOKEN" | podman login registry.odigos.io -u odigos --password-stdin

Manually generate a Docker config JSON pull secret for local Docker or Podman. Use this when login is not available, or you need an auth file for CI.

export ODIGOS_DOCKER_AUTH=$(echo -n "odigos:$ODIGOS_TOKEN" | base64)
cat <<EOF > odigos-dockerconfig.json
{
  "auths": {
    "registry.odigos.io": {
      "username": "odigos",
      "password": "$ODIGOS_TOKEN",
      "auth": "$ODIGOS_DOCKER_AUTH"
    }
  }
}
EOF

For Docker, write the file to the default config path (this overwrites ~/.docker/config.json if it already exists):

mkdir -p ~/.docker
cp odigos-dockerconfig.json ~/.docker/config.json

To keep your existing Docker config, use a dedicated directory instead:

mkdir -p /tmp/odigos-docker
cp odigos-dockerconfig.json /tmp/odigos-docker/config.json
export DOCKER_CONFIG=/tmp/odigos-docker

For Podman, write the file to the default auth path:

mkdir -p ~/.config/containers
cp odigos-dockerconfig.json ~/.config/containers/auth.json

Or pass the file per command:

podman pull --authfile odigos-dockerconfig.json registry.odigos.io/odigos-scheduler:$VERSION

Create a Docker registry pull secret when an in-cluster Job, GitOps tool, or other Kubernetes process needs to pull from registry.odigos.io.

kubectl create secret docker-registry odigos-enterprise-registry \
  --namespace odigos-system \
  --docker-server=registry.odigos.io \
  --docker-username=odigos \
  --docker-password="$ODIGOS_TOKEN"
kubectl label secret odigos-enterprise-registry -n odigos-system odigos.io/system-object=true

You can use a different secret name if this credential is only for your mirroring pipeline. Use the name odigos-enterprise-registry if Odigos itself will pull from registry.odigos.io.Or apply the secret declaratively. To do so, first generate the auth value with:

echo -n "odigos:$ODIGOS_TOKEN" | base64

Then apply:

apiVersion: v1
kind: Secret
metadata:
  name: odigos-enterprise-registry
  namespace: odigos-system
  labels:
    odigos.io/system-object: "true"
type: kubernetes.io/dockerconfigjson
stringData:
  .dockerconfigjson: |
    {
      "auths": {
        "registry.odigos.io": {
          "username": "odigos",
          "password": "<TOKEN>",
          "auth": "<BASE64_OF_odigos:TOKEN>"
        }
      }
    }

The pull, tag, and push examples below use Docker. If you authenticated with Podman, replace docker with podman.

Step 3: Pull the Images

Start by pulling the required images from the enterprise registry (registry.odigos.io) onto your local machine or CI environment:

docker pull registry.odigos.io/odigos-scheduler:$VERSION
docker pull registry.odigos.io/odigos-enterprise-instrumentor:$VERSION
docker pull registry.odigos.io/odigos-ui:$VERSION
docker pull registry.odigos.io/odigos-autoscaler:$VERSION
docker pull registry.odigos.io/odigos-enterprise-odiglet:$VERSION
docker pull registry.odigos.io/odigos-enterprise-collector:$VERSION
docker pull registry.odigos.io/odigos-victoria-metrics:$VERSION

If you are using the k8s-init-container mount method make sure the odigos-agents image is also pulled, as it’s required by the injected InitContainer. This is not the default configuration, if you’re unsure what this means, you can safely ignore this step and continue with the standard setup.

docker pull registry.odigos.io/odigos-enterprise-agents:$VERSION

Odigos component images are published in multi-arch for ARM64 and AMD64 architectures. When pulling these images, be sure to specify the correct architecture for the environment they will be deployed.

docker pull --platform $PLATFORM registry.odigos.io/odigos-scheduler:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-enterprise-instrumentor:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-ui:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-autoscaler:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-enterprise-odiglet:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-enterprise-collector:$VERSION
docker pull --platform $PLATFORM registry.odigos.io/odigos-victoria-metrics:$VERSION

Step 4: Tag the Images

Next, Tag each image with your custom Docker registry prefix:

docker tag registry.odigos.io/odigos-scheduler:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-scheduler:$VERSION
docker tag registry.odigos.io/odigos-enterprise-instrumentor:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-instrumentor:$VERSION
docker tag registry.odigos.io/odigos-ui:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-ui:$VERSION
docker tag registry.odigos.io/odigos-autoscaler:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-autoscaler:$VERSION
docker tag registry.odigos.io/odigos-enterprise-odiglet:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-odiglet:$VERSION
docker tag registry.odigos.io/odigos-enterprise-collector:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-collector:$VERSION
docker tag registry.odigos.io/odigos-victoria-metrics:$VERSION $CUSTOM_DOCKER_REGISTRY/odigos-victoria-metrics:$VERSION

Note: Enterprise images are hosted at registry.odigos.io. Image names are odigos-<component> or odigos-enterprise-<component> without an embedded keyval/ path segment. If you previously mirrored images under an older layout, re-tag them to match this naming when pushing to your custom registry.

Note: Odigos Enterprise now runs a dedicated collector image, odigos-enterprise-collector, in place of odigos-collector. If you were already mirroring odigos-collector, mirror odigos-enterprise-collector as well before upgrading, otherwise the gateway and the node collectors will fail to pull.

Step 5: Push the Images

Now, push the tagged images to your custom Docker registry:

docker push $CUSTOM_DOCKER_REGISTRY/odigos-scheduler:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-instrumentor:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-ui:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-autoscaler:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-odiglet:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-enterprise-collector:$VERSION
docker push $CUSTOM_DOCKER_REGISTRY/odigos-victoria-metrics:$VERSION

Step 6: Configure Access for Private Registries

If your Docker registry is private, configure your Kubernetes cluster to pull images from it. Refer to the official Kubernetes documentation for guidance: Pull an Image from a Private Registry.

Note: To ensure your Odigos deployments and daemonsets can pull images from a private registry, patch them to add the image pull secret. Use the following commands:

export ODIGOS_NAMESPACE=<NAMESPACE-WHERE-ODIGOS-IS-INSTALLED>
export IMAGE_PULL_SECRET=<NAME-OF-IMAGE-PULL-SECRET>
kubectl patch deployment odigos-ui -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch deployment odigos-scheduler -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch deployment odigos-instrumentor -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch deployment odigos-autoscaler -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch deployment odigos-gateway -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch deployment odigos-victoriametrics -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch daemonset odiglet -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'
kubectl patch daemonset odigos-data-collection -n $ODIGOS_NAMESPACE \
--type='json' -p='[{"op": "add", "path": "/spec/template/spec/imagePullSecrets", "value": [{"name": '$IMAGE_PULL_SECRET'}]}]'

Step 7: Install Odigos Using Custom Images

Finally, install Odigos using the images from your custom Docker registry:

Odigos CLI
Helm Chart

odigos install --image-prefix=$CUSTOM_DOCKER_REGISTRY --onprem-token $ODIGOS_TOKEN

helm repo update
helm upgrade --install odigos odigos/odigos --namespace odigos-system --create-namespace --set imagePrefix=$CUSTOM_DOCKER_REGISTRY --set onPremToken=$ODIGOS_TOKEN
kubectl label namespace odigos-system odigos.io/system-object="true"

Getting Started

Odigos AI

Instrumentations

Odigos Pipeline

Destinations

Concepts

Authentication

Contribution Guidelines

Install Odigos Images from a Custom Docker Registry

Tagging and Pushing Images

Step 1: Set Environment Variables

Step 2: Authenticate to the Enterprise Registry

Step 3: Pull the Images

Step 4: Tag the Images

Step 5: Push the Images

Step 6: Configure Access for Private Registries

Step 7: Install Odigos Using Custom Images

​Tagging and Pushing Images

​Step 1: Set Environment Variables

​Step 2: Authenticate to the Enterprise Registry

​Step 3: Pull the Images

​Step 4: Tag the Images

​Step 5: Push the Images

​Step 6: Configure Access for Private Registries

​Step 7: Install Odigos Using Custom Images

Tagging and Pushing Images

Step 1: Set Environment Variables

Step 2: Authenticate to the Enterprise Registry

Step 3: Pull the Images

Step 4: Tag the Images

Step 5: Push the Images

Step 6: Configure Access for Private Registries

Step 7: Install Odigos Using Custom Images