Skip to content

docs: add image labels and annotations documentation #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mnencia wants to merge 1 commit into
base: main
Choose a base branch
from
+41 −0
Open

docs: add image labels and annotations documentation #46

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,3 +117,44 @@ This scheme ensures:
- Alignment with the upstream `postgres-containers` base images
- Explicit PostgreSQL and extension versioning
- Multi-distro support

---

## Image Labels

Each extension image includes OCI-compliant labels for runtime inspection
and tooling integration. These metadata fields enable CloudNativePG and
other tools to identify the base PostgreSQL version and OS distribution.

### CloudNativePG-Specific Labels

| Label | Description | Example |
| :--- | :--- | :--- |
| `io.cloudnativepg.image.base.name` | Base PostgreSQL container image | `ghcr.io/cloudnative-pg/postgresql:18-minimal-bookworm` |
| `io.cloudnativepg.image.base.pgmajor` | PostgreSQL major version | `18` |
| `io.cloudnativepg.image.base.os` | Operating system distribution | `bookworm` |

### Standard OCI Labels

In addition to CloudNativePG-specific labels, all images include standard OCI
annotations as defined by the [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md):

| Label | Description |
| :--- | :--- |
| `org.opencontainers.image.created` | Image creation timestamp |
| `org.opencontainers.image.version` | Extension version |
| `org.opencontainers.image.revision` | Git commit SHA |
| `org.opencontainers.image.title` | Human-readable image title |
| `org.opencontainers.image.description` | Image description |
| `org.opencontainers.image.source` | Source repository URL |
| `org.opencontainers.image.licenses` | License identifier (Apache-2.0) |

You can inspect these labels using container tools:

```bash
# Using docker buildx imagetools
docker buildx imagetools inspect <image> --raw | jq '.annotations'

# Using skopeo
skopeo inspect docker://<image> | jq '.Labels'
```