buildimage 1.9.0

Build Docker images for use in Kubernetes deployments

buildimage

Build Docker images from git source for use in Kubernetes deployments. The build images can be tagged with configurable values. The recomended way is to tag it with the tree hash for the docker folder. This is the way the example below use.

By using the tree-hash the source code for building the image is traceable and you can create one complete commit for a change. If using commit hash, two commits is needed. One for the image change and one follow up for the deployment change (kustomize/helm/yaml).

The script uses a file named images.yaml to describe what images to build and what deployments to patch with new tags. Built images will also have some labels with metadata defined. The YAML file can use facts using the Jinja2 template format {{ name }}.

Installation

Install from PyPI:

pip install buildimage

Usage

Run the buildimage command in a directory containing an images.yaml file or specify the directory as an argument:

buildimage [OPTIONS] IMAGES_FILE

Exit codes:

• 0: Ok
• 1: Ok, but built images are dirty with local modifications
• 2: Fail

Options

• --nopush: Skip pushing built images
• --image IMAGE: Only build named images (can be specified multiple times)
• IMAGES_FILE: Path to the images.yaml file (default: ./images.yaml)

Configuration

Create an images.yaml file in your project root with the following format:

images:
  - name: "image name"               (required)
    directory: "build-directory"     (required, relative to this images file)
    dockerFile: "Dockerfile"         (relative to directory)
    target: "docker-file-target"     (default is none)
    tags:                            (required)
      - "tree-{{treeHash}}"          (first tag is later available as {{tag}})
      - "latest"
    labels:
      - name: com.mydomain.repository
        value: "{{repository}}"
    buildArgs:
      - name: "build-arg-name"
        value: "build-arg-value"
    deployments:
      - path: "path/to/deployment.yaml"
        match: "regex-to-match"
        replace: "{{tag}}"           (default value)
      - kustomize: "../development/kustomize.yaml"
        name: "{{name}}"             (default value)
        newTag: "{{tag}}"            (default value)

Available Facts

The following facts are available for templating in images.yaml:

• {{branch}}: Current Git branch
• {{commit}}: Hash for current HEAD commit
• {{login}}: Currently logged in user performing build
• {{name}}: Name of current image being built (without tags)
• {{remote}}: Git remote name
• {{repositoryFull}}: Full repository URL
• {{repository}}: Repository URL without user info
• {{tag}}: Tag used for first built image tag (same as tag0. also tag[1..3] are available)
• {{top}}: Top directory path (directory for this images.yaml file)
• {{topTreeHash}}: Git tree hash of the top directory
• {{treeHash}}: Git tree hash of the image directory (per image)

Labels

Except the custom labels defined in the images.yaml file following labels will be added for the image:

• org.opencontainers.image.topTreeHash
• org.opencontainers.image.source
• org.opencontainers.image.revision
• org.opencontainers.image.user
• org.opencontainers.image.buildimage

Example

See the tests/docker/ directory for a complete example with test images and deployment updates.

TODO

• Add labels:
  • org.opencontainers.image.base.digest
  • org.opencontainers.image.base.name see https://github.com/opencontainers/image-spec/blob/main/annotations.md
  • Tolerate when not working in a git repository or no remote configured.

Make release

• bumpver update --minor
• uv build
• uv publish