Fix a typo in the annotations and in the renovate customManager for barman. Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
5.6 KiB
Building PostgreSQL Container Images for CloudNativePG
This guide outlines the process for building PostgreSQL operand images for CloudNativePG using Docker Bake and a GitHub workflow.
The central component of this framework is the
Bake file (docker-bake.hcl
).
Prerequisites
Ensure the following tools and components are available before proceeding:
- Docker Buildx: A CLI plugin for advanced image building.
- Build Driver for Multi-Architecture Images: For example,
docker-container
(see Build Drivers and "Install QEMU Manually"). - Distribution Registry: Formerly known as Docker Registry, to host and manage the built images.
Verifying Requirements
To confirm your environment is properly set up, run:
docker buildx bake --check
If errors appear, you may need to switch to a different build driver. For
example, use the following commands to configure a docker-container
build
driver:
docker buildx create \
--name docker-container \
--driver docker-container \
--use \
--driver-opt network=host \
--bootstrap
Note: The
--driver-opt network=host
setting is required only for testing when you push to a distribution registry listening onlocalhost
.
Note: This page is not intended to serve as a comprehensive guide for building multi-architecture images with Docker and Bake. If you encounter any issues, please refer to the resources listed above for detailed instructions and troubleshooting.
Default Target
The default
target in Bake represents a Cartesian product of the following
dimensions:
- Base Image
- Type (e.g.
minimal
orstandard
) - Platforms
- PostgreSQL Versions
Building Images
To build PostgreSQL images using the default
target — that is, for all the
combinations of base image, format, platforms, and PostgreSQL versions — run:
docker buildx bake --push
Note: The
--push
flag is required to upload the images to the registry. Without it, the images will remain cached within the builder container, making testing impossible.
If you want to limit the build to a specific combination, you can specify the
target in the VERSION-TYPE-BASE
format. For example, to build an image for
PostgreSQL 17 with the minimal
format on the trixie
base image:
docker buildx bake --push postgresql-17-minimal-trixie
You can also limit the build to a single platform, for example AMD64, with:
docker buildx bake --push --set "*.platform=linux/amd64"
The two can be mixed as well:
docker buildx bake --push \
--set "*.platform=linux/amd64" \
postgresql-17-minimal-trixie
The Distribution Registry
The images must be pushed to any registry server that complies with the OCI Distribution Specification.
By default, the build process assumes a registry server running locally at
localhost:5000
. To use a different registry, set the registry
environment
variable when executing the docker
command, as shown:
registry=<REGISTRY_URL> docker buildx ...
Local Testing
You can test the image-building process locally if you meet the necessary prerequisites.
To do this, you'll need a local registry server. If you don't already have one, you can deploy a temporary, disposable distribution registry with the following command:
docker run -d --rm -p 5000:5000 --name registry registry:3
This command runs a lightweight, temporary instance of the registry:3
container on port 5000
.
Image Signing Workflow
Postgres operand images are securely signed with cosign
based on their digest through a GitHub workflow, using the
cosign-installer
action, which leverages
short-lived tokens issued through OpenID Connect.
PostgreSQL Preview Versions
PostgreSQL delivers a new major release every year. Before the stable version
is published, preview builds are made available in the form of beta releases
(e.g. beta1
) and one or more release candidates (e.g. rc1
).
Once the first beta of a new major release is published as a Debian package,
you can start building preview images by updating the
postgreSQLPreviewVersions
array in the docker-bake.hcl
file. For example:
postgreSQLPreviewVersions = [
"19~beta1",
]
NOTE: Always use the Debian package naming convention when specifying
preview versions (e.g. 19~beta1
, 19~rc1
).
To confirm that version 19 is included in the build process, run:
docker buildx bake --print
IMPORTANT: Versions listed in postgreSQLPreviewVersions
are automatically
excluded if the same version is already available as a stable release in the
postgreSQLVersions
array. Although this safeguard prevents duplication, the
postgreSQLPreviewVersions
array should be cleared once a preview version is
promoted to stable (e.g. when 19~rc1
becomes 19.0
).
Trademarks
Postgres, PostgreSQL and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada, and used with their permission.