kadet-hub logokadet-hub

Docker Compose and Kubernetes files compiled from one class

Miniflux and PostgreSQL from one Kapitan inventory, deployed to kind and started with docker compose up, and what does not map between the two.

Many self-hosted apps ship a Docker Compose file. Teams that run some of them on a Docker host and others on Kubernetes end up with a Compose file and a set of manifests for the same app, with the image, the environment and the passwords written twice. This post keeps one Kapitan inventory with two targets that include the same class. One compiles Kubernetes manifests, the other a Compose file.

The project is compose-kubernetes in kadet-hub/examples. Its check script deploys the first target to a new kind cluster and starts the second with docker compose up on the CI runner, on every change and once a week. The app is Miniflux, a feed reader, with its PostgreSQL database, from the recipe miniflux 1.0.0. That recipe was migrated from Miniflux’s own Compose file, so the post also shows how much of that file comes back.

The shared class

inventory/classes/miniflux.yml is what both targets include:

classes:
  - recipes.miniflux.miniflux
  - recipes.miniflux.db
parameters:
  applications:
    miniflux:
      database:
        user: miniflux
        name: miniflux
        password: ?{base64:miniflux/database-password||random:str:32}
      admin:
        username: admin
        password: ?{base64:miniflux/admin-password||random:str:24}

The two classes it includes come with the recipe. They define the components miniflux and miniflux-db in the format of the kubernetes generator: the images pinned by digest, the environment, a readiness probe that runs pg_isready in the database container, and a volume for PostgreSQL’s data. Miniflux reads its database connection from DATABASE_URL, which the recipe builds from the user, the name and the password set here.

The passwords are refs. On the first compile, the random:str function creates each value from letters, digits, - and _. A URL reserves none of them, and the database password ends up in DATABASE_URL. Kapitan stores the values in the refs directory. The compiled output holds a ref tag such as ?{base64:miniflux/database-password:86e11e39} until --reveal or kapitan refs --reveal replaces it with the value. The base64 backend encrypts nothing. A real project uses gpg, a cloud KMS or Vault for the same refs.

Two targets

The target cluster takes the recipe as a whole:

classes:
  - recipes.miniflux
  - miniflux
parameters:
  namespace: miniflux
  kapitan:
    vars:
      target: cluster
  generators:
    kubernetes:
      namespaces:
        miniflux:
          labels:
            pod-security.kubernetes.io/enforce: baseline
  components:
    miniflux:
      healthcheck:
        readiness:
          type: http
          port: http
          path: /healthcheck

recipes.miniflux is the recipe’s init.yml. It includes the two component classes again and adds the kubernetes generator’s pin and compile entry. The target adds the namespace, at the Pod Security level baseline, because the postgres image starts as root.

It also adds a readiness probe for Miniflux, which the recipe lacks. /healthcheck answers OK once Miniflux reaches its database. Without the probe, the rollout counted Miniflux as available as soon as the container started. In the first CI run, check then opened a port-forward to a Miniflux that did not listen yet, and the port-forward ended at the refused connection. The probe is an HTTP request from the kubelet, which a Compose health check cannot express, so it belongs in this target. In the shared class it fails the compile of compose.

The target compose cannot include init.yml, because its compile entry would run the kubernetes generator in this target as well. Setting compile: [] in the target does not remove that entry. In a local compile with Kapitan 0.36.3 and the omegaconf backend, the generator still ran. So the target gets the components through the shared class only. That is also why the shared class sets the database user and name and the admin’s username, the three values init.yml sets too. What the target adds is the compile entry for the Compose file and what only a Docker host needs:

classes:
  - miniflux
parameters:
  kapitan:
    vars:
      target: compose
    compile:
      - input_type: kadet
        input_paths:
          - components/compose
        output_path: .
        output_type: yml
  compose:
    services:
      miniflux:
        ports:
          - 127.0.0.1:8080:8080
        depends_on:
          miniflux-db:
            condition: service_healthy
        restart: unless-stopped
      miniflux-db:
        restart: unless-stopped

From components to a Compose file

kadet-hub’s docker generator 1.0.2 renders Dockerfiles, not Compose files. The Compose file therefore comes from components/compose/__init__.py, a kadet component of 77 lines in the example. It reads parameters.components, the input of the kubernetes generator, and maps the keys the recipe uses:

Component key Compose
image image
env, plain value environment, as a string
env with secretKeyRef to the component’s Secret environment, with the value from the Secret’s string_data
healthcheck.readiness of type command healthcheck with test: [CMD, ...], interval, timeout and retries from the probe or the kubelet’s defaults
volume_mounts of a volume_claims entry a named volume, mounted at mount_path
application, type, ports, service, volume_claims dropped

Any other key fails the compile with no Compose mapping for and the key. This is deliberate. A key that the cluster gets and the Docker host silently does not is the drift this setup is meant to prevent. After the mapping, the component merges the target’s compose.services over the result.

Compiled without --reveal, the target compose writes compiled/compose/compose.yml. This is the file from the CI run below:

services:
  miniflux:
    depends_on:
      miniflux-db:
        condition: service_healthy
    environment:
      ADMIN_PASSWORD: ?{base64:miniflux/admin-password:80986ca4}
      ADMIN_USERNAME: admin
      CREATE_ADMIN: '1'
      DATABASE_URL: postgres://miniflux:?{base64:miniflux/database-password:474bdc35}@miniflux-db/miniflux?sslmode=disable
      DEBUG: '1'
      RUN_MIGRATIONS: '1'
    image: miniflux/miniflux:2.3.4@sha256:72e49f513a63104506aab98ba8cfc3a409d4fde23550a583dec07ec941f1e94e
    ports:
      - 127.0.0.1:8080:8080
    restart: unless-stopped
  miniflux-db:
    environment:
      POSTGRES_DB: miniflux
      POSTGRES_PASSWORD: ?{base64:miniflux/database-password:474bdc35}
      POSTGRES_USER: miniflux
    healthcheck:
      interval: 10s
      retries: 3
      test:
        - CMD
        - pg_isready
        - -U
        - miniflux
      timeout: 30s
    image: postgres:18.6@sha256:edb0c08dc33befd0262ab3b5cf1c4f3f8cfd8b09e88c05b45adee29d6761ddb6
    restart: unless-stopped
    volumes:
      - miniflux-db:/var/lib/postgresql
volumes:
  miniflux-db: {}

One image, both outputs

To move Miniflux to another release before the recipe does, the shared class sets the image of the component:

  components:
    miniflux:
      image: miniflux/miniflux:2.3.5

check does this in a copy of the inventory, with the recipe’s image and the next patch version, compiles both targets with and without the change, and fails unless the image line of the Deployment and of compose.yml changed and nothing else. It only compiles that version, so it leaves out the digest. The diff from the CI run:

diff -ru before/compiled/cluster/manifests/miniflux/miniflux-deploy.yml after/compiled/cluster/manifests/miniflux/miniflux-deploy.yml
--- before/compiled/cluster/manifests/miniflux/miniflux-deploy.yml
+++ after/compiled/cluster/manifests/miniflux/miniflux-deploy.yml
@@ -41,7 +41,7 @@
                   name: miniflux
             - name: DEBUG
               value: '1'
-          image: miniflux/miniflux:2.3.4@sha256:72e49f513a63104506aab98ba8cfc3a409d4fde23550a583dec07ec941f1e94e
+          image: miniflux/miniflux:2.3.5
           imagePullPolicy: IfNotPresent
           name: miniflux
           ports:
diff -ru before/compiled/compose/compose.yml after/compiled/compose/compose.yml
--- before/compiled/compose/compose.yml
+++ after/compiled/compose/compose.yml
@@ -10,7 +10,7 @@
       DATABASE_URL: postgres://miniflux:?{base64:miniflux/database-password:474bdc35}@miniflux-db/miniflux?sslmode=disable
       DEBUG: '1'
       RUN_MIGRATIONS: '1'
-    image: miniflux/miniflux:2.3.4@sha256:72e49f513a63104506aab98ba8cfc3a409d4fde23550a583dec07ec941f1e94e
+    image: miniflux/miniflux:2.3.5
     ports:
       - 127.0.0.1:8080:8080
     restart: unless-stopped

Both compiles run without --reveal, so the diff holds ref tags and no password.

Deployed both ways

On kind, check applies the revealed output of the target cluster:

kapitan compile -t cluster --reveal
kubectl apply -f compiled/cluster/manifests/miniflux-namespace.yml
kubectl apply -R -f compiled/cluster/manifests -l name=miniflux-db
kubectl -n miniflux rollout status statefulset/miniflux-db
kubectl apply -R -f compiled/cluster/manifests

The Namespace goes first, because kubectl apply -R reads the directory miniflux/ before the file miniflux-namespace.yml next to it. The database goes next, selected by the name label the generator puts on every object, and check waits for its rollout. That step stands in for the depends_on of the Compose file, which has no counterpart in Kubernetes. Miniflux exits while PostgreSQL refuses connections, and the kubelet restarts it with growing delays. In a local run with everything applied at once, Miniflux sat in CrashLoopBackOff when check stopped on it.

On the Docker host, no file has to hold the passwords. check compiles the target compose without --reveal and reveals into the standard input of docker compose:

kapitan refs --reveal -f compiled/compose/compose.yml |
  docker compose -p miniflux -f - up -d --wait

--wait returns once PostgreSQL reports healthy and Miniflux runs. The values still end up in the containers’ environment, where docker inspect shows them.

On both runtimes check then runs the same steps against Miniflux’s port, through a port-forward to the Service on kind and through the published port under Compose. /healthcheck must answer OK. Logged in as the admin with the password from the ref, /v1/version must report the recipe’s tag, and a category created through /v1/categories must come back in the list. A category is a row in PostgreSQL, so the last step shows that Miniflux reached its database with the password from the other ref.

What the CI run showed

Run 42006701130 of the examples workflow tested commit 6991df2 of kadet-hub/examples#147 on 5 November 2026, on GitHub’s ubuntu-24.04 runner, with docker compose v5.7.0 and the kind node image kindest/node:v1.37.0. The durations below come from the log’s timestamps or are what check printed, in whole seconds.

Verifying the index, the recipe and the generator and pulling them took 12 seconds. All compiles, the changed image and the refused security_profile included, were done 29 seconds after check started. kind had the cluster ready 37 seconds later. The database, then Miniflux, were rolled out 23 seconds after the first kubectl apply. Under Compose, the step from kapitan refs --reveal to a running Miniflux took 18 seconds, image pulls included. The end of the log, without Compose’s pull progress:

deployed to kind in 23s
EX-30: Miniflux 2.3.4 on kind answers /healthcheck, stored and listed category 2
Docker Compose version v5.7.0
started with docker compose in 18s
miniflux miniflux/miniflux:2.3.4@sha256:72e49f513a63104506aab98ba8cfc3a409d4fde23550a583dec07ec941f1e94e Up Less than a second
miniflux-db postgres:18.6@sha256:edb0c08dc33befd0262ab3b5cf1c4f3f8cfd8b09e88c05b45adee29d6761ddb6 Up 11 seconds (healthy)
EX-30: Miniflux 2.3.4 on compose answers /healthcheck, stored and listed category 2
compose-kubernetes: passed in 111s

On both runtimes the new category got the ID 2. Miniflux creates the category All for a new user, and each runtime started with an empty database.

How much of Miniflux’s Compose file comes back

The recipe was migrated from contrib/docker-compose/basic.yml of Miniflux 2.3.4. Compiled back, the file differs in these places:

Miniflux’s file Target compose
service db, container_name: postgres service miniflux-db, container named by Compose; the recipe renames the service and drops container_name
miniflux/miniflux:latest, postgres:latest 2.3.4 and 18.6, both pinned by digest in the recipe
passwords secret and test123 refs with random values
ports: ["80:8080"] 127.0.0.1:8080:8080, from the target
restart: always restart: unless-stopped, from the target
health check every 10s with start_period: 30s every 10s with a timeout of 30s and 3 retries; the recipe drops start_period

depends_on with condition: service_healthy comes back from the target. The environment of both services and the volume come back from the recipe’s components with the same names, and with the same values apart from the passwords and the host name miniflux-db in DATABASE_URL.

What does not map

Some of what the cluster gets has no counterpart on a Docker host. Apart from the refusal of security_profile, check does not test these differences.

The Service

On kind, the Service miniflux listens on port 80 and forwards to the container’s 8080. Compose has no Service. Services reach each other by service name on the container port, as Docker’s documentation describes. DATABASE_URL names the host miniflux-db and no port, so the same URL works on both runtimes. A client of Miniflux uses port 80 in the cluster and 8080 on the Docker host.

Probes

The component turns the readiness probe of miniflux-db into a Compose health check with the same command. On Kubernetes the probe decides whether the pod gets traffic through the Service. Under Compose the status feeds depends_on and docker compose ps. A liveness probe restarts a container that still runs, while Docker’s restart policies act on a container that stops (Docker’s documentation). A Docker health check runs inside the container, so HTTP, TCP and gRPC probes, which the kubelet runs from outside, need a client in the image. The component refuses liveness and startup probes and those probe types. The HTTP probe that the target cluster adds for Miniflux is one of them.

Pod Security

security_profile fills the fields of a Pod Security level in a pod. In the shared class it fails the compile of compose. check adds it to a copy of the class and requires that failure:

EX-30b: the target compose refuses security_profile in the shared class: components.miniflux: no Compose mapping for ['security_profile']

Compose has fields for some of the same settings, such as user, cap_drop and security_opt: [no-new-privileges:true]. Nothing on a Docker host refuses a container by level, as the Namespace’s label pod-security.kubernetes.io/enforce: baseline does in the cluster. A key that only one runtime has a use for belongs in that runtime’s target.

NetworkPolicy

The recipe renders none. On Compose, every service on the project’s network reaches every port of the others. Separate networks keep services apart, but have no port rules.

Secrets

On Kubernetes the passwords sit in Secrets, and the pods’ environment refers to them. Compose’s secrets are files mounted into the container, and no environment variable can refer to one. The component writes the value into environment.

Volume size

The volume claim asks for 1Gi. A named volume of Docker’s local driver, as here, has no size limit.

Running it

You need kind, kubectl, oras, uv, jq, curl, Docker with the compose plugin, and gh logged in:

$ git clone https://github.com/kadet-hub/examples
$ cd examples/compose-kubernetes
$ ./check

check verifies the recipe and the kubernetes generator against kadet-hub’s signed index and their attestations before it pulls them by digest, and does not use kapitan compile --fetch. The Pi-hole post shows the commands.