# Images and Registries Read this page if your cluster can't pull from public registries, or if every image must come from a registry you control. It lists every image Monad runs, how to copy them into your registry or serve them through pull-through caches, and which pull secrets each pod gets. Set this up before the first install, because a pod that can't pull its image never starts. :::note[Merge snippets into your values file] Each snippet gives full paths from the top-level key. Your values file already has some of these keys, such as `global` in every example file. Add a snippet's settings under the key you already have: a second copy of a top-level key silently replaces the first. See [Install](/docs/guides/self-managed/install). ::: ## Every image Monad runs Monad's images are published on Docker Hub as `monadinc/` and need the credentials Monad support gives you. The example values files `minimal.yaml` and `local-auth-external-postgres.yaml` point `image.repository` at `registry-1.docker.io/monadinc/`. With neither `image.repository` nor `global.image.registry` set, the chart pulls Monad's images from `ghcr.io/monad-inc/`, where those credentials don't work. | Image | What runs it | How to move it | | --- | --- | --- | | `monadinc/api` | `api` and its migrations init container, `api-grpc`, `eventhandler`, `http-input`, `l4-input`, `quota-service-cron` and the `partition-manager` CronJob | `image.repository` or `global.image.registry`; one component alone with its own `image.repository`, such as `api.image.repository` | | `monadinc/ui`, `monadinc/docs`, `monadinc/mcp` | `ui`, `docs`, `mcp` | The same | | `monadinc/pipeline-operator` | The operator, and the scheduled-input controller pods it creates | The same | | `monadinc/inputs` | `cisa-kev-data-ingest`, `gadb-data-ingest`, `community-transform-ingest`, and the input pods the operator creates | The same | | `monadinc/outputs`, `monadinc/transforms`, `monadinc/enrichments` | The pipeline pods the operator creates | The same; see the note below the table | | `monadinc/alerts` | Each organization's alert service, created by the operator | The same | | `monadinc/schema-drift-detection` | The schema detection sidecar on pipeline pods | The same | | `nats` (Docker Hub) | NATS servers | `global.image.registry`; alone with `nats.container.image.registry` or `fullImageName` | | `natsio/nats-server-config-reloader` (Docker Hub) | The config reloader sidecar on each NATS server | `global.image.registry`; alone with `nats.reloader.image.registry` or `fullImageName` | | `natsio/nats-box` (Docker Hub) | `nats-box`, and the NATS `helm test` pod | `global.image.registry`; alone with `nats.natsBox.container.image.registry` or `fullImageName` | | `victoriametrics/vmstorage`, `vmselect`, `vminsert`, `vmalert` (Docker Hub) | VictoriaMetrics, tagged by the VictoriaMetrics operator unless you set a tag | `global.image.registry`; alone with `victoriametrics..image.repository` and `tag` | | `victoriametrics/operator:config-reloader-` (Docker Hub) | The config reloader sidecar on `vmalert` | `victoriametrics.vmalert.spec.configReloaderImage` | | `ghcr.io/cloudnative-pg/postgresql` | Postgres, tagged by the CloudNativePG operator | `postgresql.cnpg.spec.imageName` | | The CloudNativePG operator's own image | An init container in each Postgres pod | Wherever you installed the operator from | | `docker.dragonflydb.io/dragonflydb/dragonfly` | Dragonfly, the shared cache | `dragonfly.image.repository` and `tag` | | `ghcr.io/dragonflydb/dragonfly` | Each pipeline's own Dragonfly cache, and an init container on the pipeline pods that use it | `global.image.registry`, as `/dragonflydb/dragonfly`; alone with `operator.env.MONAD_PIPELINE_STORE_IMAGE.value`, a full image reference | | `docker.io/oryd/kratos` | Kratos server, courier and migrations, with local authentication only | `global.imageRegistry`, or `kratos.image.registry`, which `global.imageRegistry` overrides | | `docker.io/busybox` | The Kratos `helm test` pod | `global.imageRegistry`, or `kratos.test.busybox.registry` | The operator builds each image it runs from a prefix and a name. The prefix, `operator.env.MONAD_PIPELINE_IMAGE_REGISTRY.value`, follows `image.repository` and `global.image.registry`, so you don't set it yourself; if your values still set it, that value wins over both. Each name and tag is in its own value, such as `operator.env.MONAD_PIPELINE_INPUT_IMAGE.value`. Each pipeline's Dragonfly is the exception: it follows `global.image.registry` but not `image.repository`, and the operator sets its path and tag. If you enable Karmada, its control plane reads `global.imageRegistry`, and the chart's Karmada pods take `karmada.box.image`, `karmada.bootstrap.image` and `karmada.register.image`. ### List the exact images and tags Each chart version pins its own tags. To list them, render the chart with the example values file you started from, using the chart you pulled with its `examples/` directory: ```bash helm template monad ./monad -n monad -f ./monad/examples/minimal.yaml > rendered.yaml # Images the chart's own pods run grep -E '^ +(image|repository|configReloaderImage|imageName): [^ ]' rendered.yaml \ | awk '{print $2}' | tr -d '"' | sort -u # Images the operator runs: the prefix, then each name and tag grep -A1 -E 'name: MONAD_[A-Z_]*IMAGE[A-Z_]*$' rendered.yaml \ | awk '/value:/ {print $2}' | tr -d '"' | sort -u ``` Render `examples/local-auth-external-postgres.yaml` too if you use local authentication, to include Kratos. The render doesn't show the images the CloudNativePG and VictoriaMetrics operators choose unless your values set them. It doesn't show the tag of each pipeline's Dragonfly either, because the operator sets it; Monad support can give you the tag for your chart version. To see which Postgres image your CloudNativePG operator would use, ask the API server for a dry run of the Cluster. The namespace must already exist: ```bash helm template monad ./monad -n monad -f ./monad/examples/minimal.yaml \ --show-only templates/cloudnative-postgres.yaml \ | kubectl apply --dry-run=server -n monad -f - -o jsonpath='{.spec.imageName}' ``` The VictoriaMetrics operator tags `vmstorage`, `vmselect` and `vminsert` with its VictoriaMetrics version plus `-cluster` (such as `v1.156.0-cluster`), `vmalert` with the version alone, and its config reloader with its own version. Its [configuration reference](https://docs.victoriametrics.com/operator/configuration/) lists the defaults for each operator release. ## Copy the images into your registry `global.image.registry` moves the Monad, NATS and VictoriaMetrics images and each pipeline's Dragonfly to one registry, given as a host with an optional path and no trailing slash. The other images take their own keys. 1. Copy each image to its path under your registry, keeping the tag: | Copy from | To | | --- | --- | | `registry-1.docker.io/monadinc/` | `/monadinc/` | | `docker.io/library/nats` | `/nats` | | `docker.io/natsio/nats-server-config-reloader` | `/natsio/nats-server-config-reloader` | | `docker.io/natsio/nats-box` | `/natsio/nats-box` | | `docker.io/victoriametrics/` | `/victoriametrics/` | | `docker.io/oryd/kratos`, with local authentication | `/oryd/kratos` | | `docker.io/library/busybox`, only to run `helm test` | `/busybox` | | `ghcr.io/dragonflydb/dragonfly`, at the tag the operator sets | `/dragonflydb/dragonfly` | | The VictoriaMetrics config reloader, Postgres, and the shared Dragonfly | Any path; you name each one in your values | The Monad images keep their Docker Hub path, `monadinc/`, which is where `global.image.registry` looks for them. To keep them at another path instead, set `image.repository` to that prefix, ending in `/`, such as `registry.example.com/monad/`. It moves every Monad image, the operator's included, and wins over `global.image.registry`. Any registry copy tool works. Log in to Docker Hub with the credentials Monad support gave you first. With skopeo, `--all` copies every architecture: ```bash skopeo copy --all \ docker://registry-1.docker.io/monadinc/api: \ docker://registry.example.com/monadinc/api: ``` 2. Point the chart at your registry. Remove `image.repository` from your values unless you set it in step 1: an `image.repository` copied from an example file keeps the Monad images on Docker Hub. ```yaml global: image: registry: registry.example.com imageRegistry: registry.example.com imagePullSecrets: - name: postgresql: cnpg: spec: imageName: registry.example.com/cloudnative-pg/postgresql: victoriametrics: vmalert: spec: configReloaderImage: registry.example.com/victoriametrics/operator:config-reloader- dragonfly: image: repository: registry.example.com/dragonflydb/dragonfly imagePullSecrets: - name: ``` `global.imageRegistry` is for Kratos; leave it out without local authentication. With local authentication, also set `kratos.imagePullSecrets` under your existing `kratos` key. To keep the VictoriaMetrics images on the tags you copied when you upgrade the operator, set `victoriametrics..image.tag` for each of the four. 3. Check that nothing still points elsewhere. Render your values and look for an image outside your registry: ```bash helm template monad ./monad -n monad -f values.yaml > rendered.yaml grep -E '^ +(image|repository|configReloaderImage|imageName): [^ ]' rendered.yaml \ | grep -v 'registry.example.com/' ``` The command prints nothing when every image the chart renders is in your registry. The images the operator runs follow `MONAD_PIPELINE_IMAGE_REGISTRY` and `MONAD_PIPELINE_STORE_REGISTRY` in the same file. `examples/private-cluster.yaml` in the chart is a complete values file for this setup, with dedicated nodes, your own PriorityClasses and NATS authentication. ## Use pull-through caches A pull-through cache serves the images of one upstream registry. Monad's images come from these: | Upstream | Images | | --- | --- | | Docker Hub | Monad's images, which are private: the cache needs the Docker Hub credentials Monad support gave you. Also NATS, VictoriaMetrics, Kratos and `busybox` | | `ghcr.io` | Postgres and each pipeline's Dragonfly | | `docker.dragonflydb.io` | The shared Dragonfly. It serves the same images as `ghcr.io/dragonflydb/dragonfly`, so a `ghcr.io` cache can stand in | The CloudNativePG operator's own image comes from wherever you installed the operator. ### Mirror on each node containerd can send pulls for a registry to a mirror, which needs no change to the chart. On each node, create `/etc/containerd/certs.d//hosts.toml`, with containerd's registry `config_path` set to `/etc/containerd/certs.d`. For example, for Docker Hub: ```toml server = "https://registry-1.docker.io" [host."https://dockerhub-cache.example.com"] capabilities = ["pull", "resolve"] ``` containerd picks the directory by the registry host in the image reference. Monad's images, referenced as `registry-1.docker.io/monadinc/...`, therefore need a directory of their own besides `docker.io`: | Directory | Covers | | --- | --- | | `docker.io` | NATS, VictoriaMetrics, Kratos and `busybox`, referenced as `docker.io` or with no host | | `registry-1.docker.io` | Monad's images, referenced as `registry-1.docker.io/monadinc/...` with the example files' `image.repository` | | `ghcr.io` | Postgres and each pipeline's Dragonfly | | `docker.dragonflydb.io` | The shared Dragonfly | Apply this through your node image or node bootstrap, so that nodes created later get it too. See containerd's [registry host configuration](https://github.com/containerd/containerd/blob/main/docs/hosts.md) for TLS, credentials and caches served under a path. ### Point the chart at the caches Without node configuration, set each image to its cache. This example uses a Docker Hub cache at `cache.example.com/docker-hub` and a `ghcr.io` cache at `cache.example.com/ghcr`. Use it instead of the snippet in [Copy the images into your registry](#copy-the-images-into-your-registry): ```yaml global: image: registry: cache.example.com/docker-hub imageRegistry: cache.example.com/docker-hub imagePullSecrets: - name: postgresql: cnpg: spec: imageName: cache.example.com/ghcr/cloudnative-pg/postgresql: victoriametrics: vmalert: spec: configReloaderImage: cache.example.com/docker-hub/victoriametrics/operator:config-reloader- dragonfly: image: repository: cache.example.com/ghcr/dragonflydb/dragonfly imagePullSecrets: - name: operator: env: MONAD_PIPELINE_STORE_IMAGE: value: cache.example.com/ghcr/dragonflydb/dragonfly: ``` - `global.image.registry` asks the Docker Hub cache for `monadinc/...`, `nats`, `natsio/...` and `victoriametrics/...`. Remove `image.repository` from your values, as in step 2 of [Copy the images into your registry](#copy-the-images-into-your-registry). If your cache needs Docker Hub's `library/` prefix for official images, also set `nats.container.image.repository: library/nats`, and `kratos.test.busybox.repository: library/busybox` to run `helm test` with local authentication. - `global.image.registry` would also send each pipeline's Dragonfly to the Docker Hub cache, but that image comes from `ghcr.io`. `MONAD_PIPELINE_STORE_IMAGE` wins over it and points the image at the `ghcr.io` cache. As a full reference it pins the tag, so update the tag when an upgrade changes it, or [mirror `ghcr.io` on each node](#mirror-on-each-node) instead. - `global.imageRegistry` is for Kratos; leave it out without local authentication. - The pull secrets hold your cache's credentials, if it needs any. Add `kratos.imagePullSecrets` under your existing `kratos` key with local authentication. ## Pull secrets A pull secret is a `kubernetes.io/dockerconfigjson` Secret in the release namespace, created as in [Image pull secret](/docs/guides/self-managed/before-you-install#image-pull-secret). Which secrets each pod gets: | Pods | Pull secrets | Their own key | | --- | --- | --- | | Monad components | `global.imagePullSecrets`, plus the top-level `imagePullSecrets` or the component's own list, which replaces the top-level one | `.imagePullSecrets` | | NATS servers and `nats-box` | `global.imagePullSecrets`, plus their own | `nats.podTemplate.merge.spec.imagePullSecrets`, `nats.natsBox.podTemplate.merge.spec.imagePullSecrets` | | Postgres | `global.imagePullSecrets`, plus its own | `postgresql.cnpg.imagePullSecrets` | | VictoriaMetrics | `global.imagePullSecrets`, plus its own | `victoriametrics.imagePullSecrets` | | Pods the operator creates | `global.imagePullSecrets`, plus their own. With both empty, a Secret named `default-pull-secret` | `operator.managedPods.imagePullSecrets` | | Dragonfly | Its own only | `dragonfly.imagePullSecrets` | | Kratos | Its own only | `kratos.imagePullSecrets` | | Karmada box, bootstrap and register pods, if enabled | `global.imagePullSecrets`, plus the top-level `imagePullSecrets` | None | | Karmada's own components, if enabled | `global.imagePullSecrets` | `karmada.global.imagePullSecrets`, which `global.imagePullSecrets` replaces | Put a secret every pod needs in `global.imagePullSecrets`, and add it to `dragonfly.imagePullSecrets` and `kratos.imagePullSecrets` when those pull from a registry that needs it. For where the other placement settings go, see [Scheduling and Resources](/docs/guides/self-managed/scheduling#give-one-workload-its-own-value).