Configuration Guide

image-syncer keeps its authentication credentials separate from its synchronization rules. By separating credentials (--auth) from image rules (--images), you can reuse login details across multiple sync files. Both configurations support YAML and JSON formats.

Registry Authentication (--auth)

The authentication file contains credential definitions, mapping registry domains to usernames, passwords, tokens, or security bypass variables.

Configuration Schema

Here is a comprehensive YAML example of an auth.yaml configuration:

# auth.yaml

# Standard private registry login with SSL
registry.cn-beijing.aliyuncs.com:
  username: "aliyun-user"
  password: "aliyun-password"

# Private registry utilizing a plain HTTP endpoint (no SSL/TLS)
localhost:5000:
  username: "admin"
  password: "admin123"
  insecure: true

# Domain-scoped Quay.io login
quay.io:
  username: "quay-robot-user"
  password: "quay-token-secret"

# Docker Hub utilizing dynamic environment variables
docker.io:
  username: "${DOCKER_USER}"
  password: "$DOCKER_PASSWORD"

Credentials Resolution and Lookup Behavior

When image-syncer initiates a transfer, it searches the authentication mapping to find matching login credentials for both the source and target registries.

  1. Longest Prefix Matching: If multiple domains match a repository URL, the tool prioritizes keys by matching prefix length. For example, if you define keys for both quay.io and quay.io/coreos, requests to quay.io/coreos/etcd will use the quay.io/coreos credentials, while other quay.io repositories will default to the general quay.io credentials.
  2. Anonymous Fallback: If a domain does not match any entry in your authentication configuration, image-syncer attempts to connect anonymously. This allows you to pull public images from registries like Docker Hub without needing to configure logins.
  3. Insecure Settings: Setting insecure: true configures the client to bypass TLS certificate validation and drop back to unencrypted HTTP when connecting to the registry. Use this option only for local development or secure internal networks.

Dynamic Environment Variable Expansion

To avoid storing plain-text secrets in your configuration files, you can use dynamic environment variable references. Format the values as "${ENV_VAR}" or "$ENV_VAR" in either YAML or JSON files:

docker.io:
  username: "${DOCKER_REGISTRY_USER}"
  password: "${DOCKER_REGISTRY_TOKEN}"

At runtime, the configuration parser automatically retrieves these values from the shell environment. If a variable is empty or not set, the tool falls back to an empty string.

Automated Google Container Registry (GCR) Tokens

To synchronize images with GCR (*.gcr.io) using service accounts:

  • Set the registry username key exactly to _oauth2_.
  • Set the password value to the Base64-encoded Service Account JSON key.

image-syncer detects this specific configuration, decodes the service account, and handles the OAuth2 token exchange and token rotation automatically.

Image Synchronization Rules (--images)

The image rules file defines mappings between source images and their destinations.

Supported Rule Syntaxes and Examples

# images.yaml

# 1. Standard Tag Mapping
# Copies alpine tag 3.18.2 to the destination, preserving the tag.
alpine:3.18.2: "localhost:5000/image-syncer-test/alpine"

# 2. Entire Repository Copy
# Leaving the tag out tells the tool to discover and copy all tags from the source repository.
quay.io/coreos/kube-rbac-proxy: "quay.io/ruohe/kube-rbac-proxy"

# 3. Explicit Tag Filtering List
# Only the specified comma-separated tags will be synchronized.
quay.io/coreos/kube-rbac-proxy:v0.11.0,v0.12.0: "quay.io/ruohe/kube-rbac-proxy"

# 4. Digest-Based Mapping
# Copies a specific, immutable content digest to the destination repository.
quay.io/coreos/kube-rbac-proxy@sha256:14b267eb38aa85fd12d0e168fffa2d8a6187ac53a14a0212b0d4fce8d729598c: "quay.io/ruohe/kube-rbac-proxy"

# 5. Regular Expression Tag Matching
# Enclosing the tag inside standard '/' delimiters treats it as a regex pattern.
# Only tags matching the regex (such as v1.1.0, v1.2.5, etc.) will be copied.
quay.io/coreos/kube-rbac-proxy:/^v1\..*/: "quay.io/ruohe/kube-rbac-proxy"

# 6. Target Tag Renaming
# Maps source tags to custom target tags. Mappings are resolved left-to-right.
quay.io/coreos/kube-rbac-proxy:v1.0,v2.0: "quay.io/ruohe/kube-rbac-proxy:v1.0-release,v2.0-release"

# 7. Multi-Destination Targets
# Push the source image to multiple targets simultaneously.
quay.io/coreos/kube-rbac-proxy:v1.1:
  - "quay.io/ruohe/kube-rbac-proxy-backup-1"
  - "quay.io/ruohe/kube-rbac-proxy-backup-2"

Unified Configuration Format (--config)

In older versions (prior to v1.2.0), registry logins and image rules were combined into a single file. This format is still supported for backwards compatibility:

{
  "auth": {
    "docker.io": {
      "username": "test-user",
      "password": "test-password"
    }
  },
  "images": {
    "nginx:latest": "my-private-registry.com/nginx:latest"
  }
}

To learn more about the internal processing stages and how task execution handles these rules, read Architecture and Core Mechanics.