.stackat.yml / option

mirrors

Most companies pull images and charts through their own registry: Harbor, Artifactory, Nexus or an ECR pull-through cache. mirrors tells Stackat which public tool such a reference stands for.

What it does#

A repository that pins harbor.acme.internal/dockerhub/library/traefik:v3.2.0, or a chart from your Artifactory, is still Traefik. Stackat maps it back in this order:

1. Your rules: a reference that starts with a rule's from is rewritten to start with its to. When several rules match, the longest from wins.
2. Automatic detection (detect: true):
   • images and OCI charts: leading path segments are dropped until the rest is a known image, reading the dropped part as the public registry it mirrors (dockerhub, ghcr, quay, k8s, gcr, ECR pull-through prefixes, or a registry host spelled out). A bare name without such a hint never matches: harbor/apps/traefik may be your own image;
   • charts from a private chart repository (Artifactory, Nexus, Harbor, ECR, ACR, Artifact Registry), by chart name, when exactly one tool has a chart of that name and the name is not generic;
   • Terraform providers from a private registry that proxies the public one (terraform.acme.internal/hashicorp/aws).

The issue, and the pull request, then says the tool is pulled through your mirror and that the target version must be mirrored there before you upgrade. An automatic match also says how to correct it, with a rule or detect: false.

Type and values#

• from is matched as a prefix of the image reference or chart repository URL, ignoring case, up to a /.
• to replaces it. Leave to empty (to: "") to drop the prefix and keep the rest as it is.
• A bare list under mirrors: is read as the rules.

Organisation and repository#

Rules from both files apply, the repository's first; across both, the longest matching from still wins. detect in the repository's file replaces the organisation's.

A platform team usually keeps the rules once, in the organisation's file.

Problems you may see#

.stackat.yml: mirrors.rules[0] needs `from` (your mirror's prefix) and `to` (the public one)
.stackat.yml: mirrors.detect must be true or false
.stackat.yml: mirrors must be a mapping (detect, rules) or a list of rules

A rule with a problem is left out; the other rules apply.

Examples#

Harbor proxy-cache projects#

mirrors:
  rules:
    - from: harbor.acme.internal/dockerhub
      to: docker.io
    - from: harbor.acme.internal/ghcr
      to: ghcr.io
    - from: harbor.acme.internal/quay
      to: quay.io

An Artifactory remote for one chart repository#

mirrors:
  rules:
    - from: https://acme.jfrog.io/artifactory/api/helm/kyverno-remote
      to: https://kyverno.github.io/kyverno

Only your rules, no guessing#

Your registry also hosts your own images under names like public ones: turn automatic detection off and list the mirrors yourself.

mirrors:
  detect: false
  rules:
    - from: 123456789012.dkr.ecr.eu-central-1.amazonaws.com/docker-hub
      to: docker.io