Skip to main content
logoTetrate Patch ServiceVersion: alpha

Discovering Images from a Private Registry

The agent recognizes a Tetrate image by the repository the release catalog publishes it under, such as docker.io/tetrate/teg-envoy. If your clusters pull Tetrate's images from your own registry instead, the agent does not recognize them, and the cluster shows a No workloads badge in the Clusters view.

To fix it, tell the agent which Tetrate image each of your images is a copy of. There are two settings for this, both under releaseCatalog in the agent's Helm values: registryAliases and extraRepositories.

Once the agent knows, it reports the image as your cluster runs it, together with the Tetrate image it copies. The Patch Service scans the Tetrate image for CVEs, because it cannot reach your registry, and shows the findings and any Upgrade available marker against the image your cluster runs. Your registry is trusted to serve what it mirrors: only an image referenced by digest is checked against what Tetrate published.

Registry Aliases​

Use registryAliases when your registry keeps Tetrate's repository paths and only adds a prefix in front of them. This is how most mirrors and pull-through caches work.

Each entry maps a registry the release catalog uses to the prefix your registry serves it under:

releaseCatalog:
  registryAliases:
    docker.io: registry.example.com/dockerhub

With this entry, the agent replaces registry.example.com/dockerhub with docker.io at the start of each image, and recognizes the image if the result is a Tetrate repository:

Image in your clusterCopy of
registry.example.com/dockerhub/tetrate/teg-envoy:distroless-v1.9.2.4docker.io/tetrate/teg-envoy:distroless-v1.9.2.4
registry.example.com/dockerhub/tetrate/teg-envoy-gateway:v1.9.2docker.io/tetrate/teg-envoy-gateway:v1.9.2
registry.example.com/dockerhub/library/nginx:1.27Not recognized: not a Tetrate image

One entry covers every Tetrate image on that registry, including components Tetrate publishes later. If you mirror images from more than one registry, add one entry for each.

Extra Repositories​

Use extraRepositories when your registry renamed Tetrate's repositories, so no prefix maps them back. Add one entry per repository, without a tag, as <your repository>=<Tetrate repository>:

releaseCatalog:
  extraRepositories:
    - registry.example.com/platform/envoy=docker.io/tetrate/teg-envoy
    - registry.example.com/platform/envoy-gateway=docker.io/tetrate/teg-envoy-gateway

With the first entry, registry.example.com/platform/envoy:distroless-v1.9.2.4 is recognized as a copy of docker.io/tetrate/teg-envoy:distroless-v1.9.2.4. The tag is kept, so your registry must keep Tetrate's tags.

Each entry covers exactly one repository, so a Tetrate component you start using later needs a new entry.

Always name the Tetrate repository

An entry can also be just your repository, such as registry.example.com/platform/envoy. The agent then reports its images, but the Patch Service does not know which Tetrate image they copy: they are never scanned, show No scan data, and get no Upgrade available marker. Add =<Tetrate repository> to every entry.

Which One to Use​

Your registrySetting
Keeps Tetrate's paths under a prefixregistryAliases, one entry per source registry
Renamed or flattened the pathsextraRepositories, one entry per repository
Does both, for different imagesBoth settings together

Images referenced by digest (...@sha256:...) need neither setting. A mirror keeps the digest, so the agent recognizes the image wherever it is served from, and finds the Tetrate image it copies from the digest.

Applying the Setting​

Add the releaseCatalog block to the agent's values. Where they live depends on how the agent was installed.

On the managed data plane, add it to agent/values-customer.yaml in your repository, or to agent/envs/<environment>/values-customer.yaml to apply it to one environment only, and open a pull request as described in Working with Your Repository. Once it merges, ArgoCD restarts the agent with the new setting.

On an agent-only install, made with tetrate onboard, the Manual connection steps, or a cloud account install, add the block to the agent's saved values and upgrade its Helm release with them, as described in Upgrading the Agent. To change only the setting, keep the chart version and image tag the release already runs.

Scanning mirrored images needs a recent agent

Agents up to 0.4.3 recognize mirrored images but do not report which Tetrate image they copy, so those images show No scan data and no Upgrade available marker. Upgrade the agent to get CVE findings and upgrade markers for them.

Checking the Result​

The agent reports as soon as it restarts. The cluster's No workloads badge clears, and expanding its row lists the containers running your mirrored images. After the next scan, their Version badges show their CVE status.

If an image is still missing, check the agent's log. The agent warns at startup about any setting that matches nothing in the catalog, for example a registry alias written the wrong way round:

kubectl logs deployment/patch-service-agent -n tetrate-dataplane-system | grep "matches nothing"
{"level":"WARN","msg":"release catalog configuration matches nothing","problem":"registry alias \"registry.example.com/dockerhub\"=\"docker.io\" matches nothing: ... so this looks reversed: did you mean \"docker.io\"=\"registry.example.com/dockerhub\"?"}

A malformed entry, such as an extra repository with a tag, stops the agent at startup, and its log names the entry.

Next Steps​