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.
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.
Every image Monad runs
Monad's images are published on Docker Hub as monadinc/<name> 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.<component>.image.repository and tag |
victoriametrics/operator:config-reloader-<operator version> (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 <registry>/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:
Code
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:
Code
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 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.
-
Copy each image to its path under your registry, keeping the tag:
Copy from To registry-1.docker.io/monadinc/<name><registry>/monadinc/<name>docker.io/library/nats<registry>/natsdocker.io/natsio/nats-server-config-reloader<registry>/natsio/nats-server-config-reloaderdocker.io/natsio/nats-box<registry>/natsio/nats-boxdocker.io/victoriametrics/<component><registry>/victoriametrics/<component>docker.io/oryd/kratos, with local authentication<registry>/oryd/kratosdocker.io/library/busybox, only to runhelm test<registry>/busyboxghcr.io/dragonflydb/dragonfly, at the tag the operator sets<registry>/dragonflydb/dragonflyThe 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/<name>, which is whereglobal.image.registrylooks for them. To keep them at another path instead, setimage.repositoryto that prefix, ending in/, such asregistry.example.com/monad/. It moves every Monad image, the operator's included, and wins overglobal.image.registry.Any registry copy tool works. Log in to Docker Hub with the credentials Monad support gave you first. With skopeo,
--allcopies every architecture:Code -
Point the chart at your registry. Remove
image.repositoryfrom your values unless you set it in step 1: animage.repositorycopied from an example file keeps the Monad images on Docker Hub.Codeglobal.imageRegistryis for Kratos; leave it out without local authentication. With local authentication, also setkratos.imagePullSecretsunder your existingkratoskey. To keep the VictoriaMetrics images on the tags you copied when you upgrade the operator, setvictoriametrics.<component>.image.tagfor each of the four. -
Check that nothing still points elsewhere. Render your values and look for an image outside your registry:
CodeThe command prints nothing when every image the chart renders is in your registry. The images the operator runs follow
MONAD_PIPELINE_IMAGE_REGISTRYandMONAD_PIPELINE_STORE_REGISTRYin 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/<upstream>/hosts.toml, with containerd's registry config_path set to /etc/containerd/certs.d. For example, for Docker Hub:
Code
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 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:
Code
global.image.registryasks the Docker Hub cache formonadinc/...,nats,natsio/...andvictoriametrics/.... Removeimage.repositoryfrom your values, as in step 2 of Copy the images into your registry. If your cache needs Docker Hub'slibrary/prefix for official images, also setnats.container.image.repository: library/nats, andkratos.test.busybox.repository: library/busyboxto runhelm testwith local authentication.global.image.registrywould also send each pipeline's Dragonfly to the Docker Hub cache, but that image comes fromghcr.io.MONAD_PIPELINE_STORE_IMAGEwins over it and points the image at theghcr.iocache. As a full reference it pins the tag, so update the tag when an upgrade changes it, or mirrorghcr.ioon each node instead.global.imageRegistryis for Kratos; leave it out without local authentication.- The pull secrets hold your cache's credentials, if it needs any. Add
kratos.imagePullSecretsunder your existingkratoskey with local authentication.
Pull secrets
A pull secret is a kubernetes.io/dockerconfigjson Secret in the release namespace, created as in 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 | <component>.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.