Ansible Role: Zot

Install and configure Zot - an OCI-native container image registry.

Dependencies

None. The binary is downloaded from the GitHub releases of project-zot/zot at version zot_version (zot-linux-amd64), so the host needs access to github.com and must be amd64.

Variables

Variable	Required	Default	Description
zot_version	No	2.1.21	Zot release version to install
zot_cve_scanning	No	false	Enable CVE scanning of images
zot_sync_credentials	No	undefined	List of sync registry credentials to avoid rate limits

Each entry of zot_sync_credentials has the keys registry, username and password. The credentials are written to /etc/zot/sync-credentials.json (mode 0600) and are secrets: keep them in sops-encrypted inventory variables.

Example

zot_version: "2.1.21"
zot_cve_scanning: true
zot_sync_credentials:
  - name: "dockerhub"
    registry: "registry-1.docker.io"
    username: "your-dockerhub-username"
    password: "replace-with-sops-encrypted-password"

Configuration

The role deploys Zot with the following defaults:

• Bind address: 127.0.0.1:5000 (put a reverse proxy in front of it)
• Storage: /var/lib/zot, with garbage collection (delay 1h, interval 24h)
• Retention: untagged images and referrers are deleted, tags not pulled within 1440h (60 days) are removed
• Config: /etc/zot/config.json
• Binary: /usr/bin/zot
• Extensions: UI and search enabled; CVE database updates every 24h when zot_cve_scanning is true
• Sync: on-demand pull-through mirrors for Docker Hub, GHCR, Codeberg, Quay, GitLab and LSCR, under the prefixes /dockerhub, /ghcr, /codeberg, /quay, /gitlab and /lscr
• Service: systemd unit zot on Debian-family systems (runs as root, memory capped at 1536M)

The binary is only downloaded again when the installed version does not contain zot_version.

Usage

Run the role through Semaphore using playbook.yaml. The playbook first runs ansible-galaxy install -f -r roles/requirements.yml on the controller to fetch the latest zot role, then executes it on all hosts, one host at a time.