Build and Push a Configurable Image

A configurable image is a bootable container image with template files that are rendered per-host at deploy time. This lets you build one image and configure it differently for each machine.

Create the image

We'll build a simple Caddy web server image as an example. Create a directory with these files:

Containerfile

FROM quay.io/fedora/fedora-bootc:44

RUN dnf -y install caddy
RUN systemctl enable caddy

COPY Caddyfile.khtmpl /etc/caddy/Caddyfile.khtmpl
COPY schema.json /etc/kheeper/schema.json

RUN bootc container lint

Caddyfile.khtmpl — a Go template that will be rendered to /etc/caddy/Caddyfile when this image is configured.

:80 {
    respond "Hello, {{ .Name }}"
}

schema.json (Optional) — validates configuration values for this image.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "Name": {
      "type": "string"
    }
  },
  "required": ["Name"],
  "additionalProperties": false
}

Build

First set the ORG var to your user organization.

ORG=$(kheeper orgs list | grep 'user-[0-9a-f]' | awk '{ print $1 }')

The kheeper.configurable=1 annotation tells the registry to extract the templates and schema when the image is pushed.

podman build --annotation kheeper.configurable=1 --arch amd64 -t kheeper.com/${ORG}/getting-started:v1 -f Containerfile .

Push

kheeper push ${ORG}/getting-started:v1

Verify

kheeper images get ${ORG}/getting-started:v1

The output will include a ConfigImage field, confirming the registry recognized the image as configurable.