Skip to main content

Keep private registry in sync

Connect docs via MCP
Important!

Some capabilities shown here may require additional enablement or licensing. Contact your Atlan representative for details.

New to mirroring?

Start with Image procurement approach for when and why to mirror Atlan images and which approach to choose (public Docker Hub, a prefix rewrite, or an image map). This guide covers the image-map implementation for keeping a mirror in sync.

If your environment blocks pulls from public registries, you mirror Atlan app images into your own private registry before the SDR Orchestrator can deploy or upgrade them. This guide describes the recommended flow to keep that mirror current:

  1. Poll Atlan for the latest images your tenant needs.
  2. Mirror any new images into your registry.
  3. Write an image map back to your object storage that maps each Atlan source image to your mirrored image.
  4. The SDR Orchestrator reads the map at install and upgrade time and pulls from your registry instead of the public source.

This works for both connector apps and the SDR Orchestrator's own image, and it doesn't require Atlan to know anything about your registry—you stay in control of what's mirrored and where it lives.

When to use this

Use this flow if you mirror images and either (a) your registry changes the image repository or tag during replication, or (b) you want a machine-readable, pollable source of truth for which images to mirror. If you simply re-host images under a single prefix with identical names and tags, the simpler containerRegistryBase / container_registry.base prefix rewrite shown in the install guides is sufficient.

How it works​

   Atlan (Global Marketplace)                 Your environment
   ┌──────────────────────────┐
   │ latest-releases endpoint │◀── 1. poll ──── your mirroring job
   └──────────────────────────┘                      │
                                       2. pull + push │ (mirror images)
                                                      ▼
                                              your private registry
                                                      │
                              3. write image map      ▼
                                       ┌──────────────────────────┐
                                       │  object storage          │
                                       │  sdr/image-map.yaml       │
                                       └──────────────────────────┘
                                                      ▲
                                       4. read on     │
                                          install /   │
                                          upgrade     │
                                              SDR Orchestrator

Prerequisites​

  • A working SDR Orchestrator installation. See Install on Docker/Podman or Install on Kubernetes.
  • An Atlan API token for your tenant (used to poll the latest-releases endpoint). See Manage API tokens.
  • Write access to the same object storage bucket the SDR is configured to use (the objectstore component in your config.yaml / values.yaml).
  • Your private registry credentials, and a host that can reach both the Atlan source registry (to pull) and your registry (to push).

Step 1: Discover images to mirror​

Poll the latest-releases endpoint for your tenant. It returns the source image reference for every app your tenant can run that's eligible for Self-Deployed Runtime, plus the SDR Orchestrator image itself.

curl -sS \
  -H "Authorization: Bearer $ATLAN_API_TOKEN" \
  "https://<your-tenant>.atlan.com/api/service/marketplace/latest-releases"

The response lists each image as a repo:tag reference under image:

{
  "releases": [
    {
      "app_id": "019aaaaa-0000-7000-8000-000000000001",
      "app_name": "teradata",
      "version": "3.1.4",
      "version_id": "019b2b7d-...",
      "image": "atlanhq/atlan-teradata-app:3.1.4"
    },
    {
      "app_id": "019d480a-25b6-7051-8596-6ce892530197",
      "app_name": "sdr-orchestrator-k8s",
      "version": "0.3.0",
      "version_id": "019cffff-...",
      "image": "atlanhq/atlan-sdr-orchestrator-k8s:0.3.0"
    }
  ]
}

Compare this list with what you've already mirrored to find what's new. The image field is the Atlan source reference—what you pull from.

Step 2: Mirror new images to your registry​

For each image returned in Step 1 that you don't already have, pull it from the Atlan source and push it to your registry. For example:

# Pull the source image (requires the Docker Hub PAT from your Atlan representative)
docker pull atlanhq/atlan-teradata-app:3.1.4

# Tag and push to your registry
docker tag atlanhq/atlan-teradata-app:3.1.4 \
  registry.mycompany.com/atlan/atlan-teradata-app:3.1.4
docker push registry.mycompany.com/atlan/atlan-teradata-app:3.1.4

You may keep the same repository name and tag, or rename either during replication—the image map in the next step records whatever mapping you choose.

Verify before you mirror

Atlan signs every image with keyless Cosign. Verify the signature before pushing it into your registry—see Verify container images.

Step 3: Write image map to object storage​

Write a YAML file to your object storage that maps each Atlan source image to its mirrored location. Upload it to the same bucket the SDR uses (for example, at the key sdr/image-map.yaml).

sdr/image-map.yaml
images:
  # Quote keys and values — they contain colons.
  # repo -> repo: covers every tag of this image; the source tag is preserved.
  "atlanhq/atlan-teradata-app": "registry.mycompany.com/atlan/atlan-teradata-app"
  "atlanhq/atlan-sdr-orchestrator-k8s": "registry.mycompany.com/atlan/atlan-sdr-orchestrator-k8s"

  # repo:tag -> repo:tag: pins a single image when you renamed the repo OR the
  # tag during replication.
  "atlanhq/atlan-teradata-app:3.1.4": "registry.mycompany.com/atlan/teradata:3.1.4-approved"

How a source image is resolved:

  • An exact repo:tag entry wins, and its value is used verbatim—so you can change the repository and the tag during replication.
  • Otherwise a bare repo entry is used, and the source tag is appended unchanged—one entry covers every version of that app.
  • If an image isn't found in the map, the SDR leaves the reference unchanged (the pull then fails with your blocked source, which surfaces the gap).
Externally managed Kubernetes releases (optional)

If the SDR Orchestrator's own Helm release is managed by an external tool (for example, Flux) under a name or namespace that differs from the default, add an optional release block so self-update targets the right release:

release:
  name: my-sdr-release          # overrides the default atlan-sdr-<deployment_name>
  storage_namespace: flux-system # namespace holding the Helm release record

Step 4: Point SDR Orchestrator at map​

Tell the SDR where the map lives in object storage. The path is a key within the object storage bucket already configured for the SDR—the SDR reads it through the same objectstore component.

Add image_map_path to the container_registry section of config.yaml:

config.yaml
container_registry:
  image_map_path: "sdr/image-map.yaml"
  # username/password are still used for the pull secret if your registry needs auth
  username: "<your-registry-username>"
  password: "<your-registry-token>"

Restart the orchestrator to pick up the config change:

docker compose up -d

When image_map_path is set, it takes precedence over the containerRegistryBase / container_registry.base prefix rewrite.

How the SDR uses the map​

The SDR Orchestrator reads the image map from object storage on every install and upgrade, including its own self-update. It resolves each image through the map before pulling, so:

  • Connector installs and upgrades pull from your registry.
  • SDR self-updates pull the orchestrator image from your registry.

Because the SDR reads the map fresh each time, you don't need to restart or reconfigure the SDR when you mirror a new image—just update the map in object storage and the next install or upgrade picks it up.

Automate the refresh​

Run Steps 1–3 on a schedule (for example, a cron job or CI pipeline) so newly published images are mirrored and recorded in the map before the SDR's hourly reconcile attempts an upgrade. A typical job:

  1. Poll latest-releases.
  2. Compare with the entries already in your image-map.yaml.
  3. For anything new: verify, pull, push, and add the mapping.
  4. Upload the updated image-map.yaml to object storage.

See also​