Skip to content

BUILD.md

Latest commit

 

History

History
167 lines (121 loc) · 5.61 KB

BUILD.md

File metadata and controls

167 lines (121 loc) · 5.61 KB

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:

  1. Docker Buildx: A CLI plugin for advanced image building.
  2. Build Driver for Multi-Architecture Images: For example, docker-container (see Build Drivers and "Install QEMU Manually").
  3. 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 on localhost.

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 or standard)
  • 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.