1# Images Configuration
2
3Configure automatic image cleanup for Docker runtime images and local registry storage.
4
5## Overview
6
7When enabled, Gordon runs a scheduled image prune job that:
8
9- Prunes dangling runtime images.
10- Applies tag retention to registry repositories.
11- Preserves the `latest` tag.
12- Removes unreferenced blobs after tag cleanup.
13
14The CLI `gordon images prune` uses the same defaults as the scheduled job (keep `latest` + 3 previous tags, both scopes enabled: dangling runtime images and registry tag retention).
15
16## Configuration
17
18```toml
19[images]
20allowed_registries = []
21require_digest = false
22
23[images.prune]
24enabled = false
25schedule = "daily"
26keep_last = 3
27```
28
29## Settings
30
31| Key | Type | Default | Description |
32|-----|------|---------|-------------|
33| `images.allowed_registries` | array | `[]` | Allowlist for external image registries. Empty means no external registries are accepted. Unqualified image names such as `nginx:latest` are treated as Docker Hub (`docker.io`) for policy checks. Gordon always allows its configured registry and rejects localhost/private/link-local registries. Include ports when needed, e.g. `"registry.example.com:5000"`. |
34| `images.require_digest` | bool | `false` | Require allowlisted external image references to use a valid `@sha256:<64 hex chars>` digest. Gordon registry images are exempt. |
35| `images.prune.enabled` | bool | `false` | Enables scheduled image cleanup |
36| `images.prune.schedule` | string | `"daily"` | Schedule preset: `hourly`, `daily`, `weekly`, `monthly` |
37| `images.prune.keep_last` | int | `3` | Number of newest non-`latest` tags kept per repository during registry cleanup (`latest` is always kept when present) |
38
39## Retention Behavior
40
41- `latest` is always preserved.
42- `keep_last` applies per repository and counts non-`latest` tags.
43- `keep_last = 0` skips registry tag/blob cleanup (runtime dangling prune still runs).
44- Negative `keep_last` values are invalid.
45
46## Related
47
48- [CLI Images Command](../cli/images.md)
49- [Configuration Reference](./reference.md)