kates

Kates Helm Chart

Chainguard's redistribution of the Kates chart, configured with Chainguard images for Kates, PostgreSQL, database readiness, backup, migration, and cleanup.

Prerequisites

Authenticate to the chart registry:

chainctl auth login
chainctl auth configure-docker --pull-token --save
helm registry login cgr.dev
kubectl create namespace kates
kubectl create secret docker-registry cgr-pull-secret \
  --docker-server=cgr.dev \
  --docker-username="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Username')" \
  --docker-password="$(echo cgr.dev | docker-credential-cgr get | jq -r '.Secret')" \
  --namespace kates

Kates requires a reachable Kafka cluster and PostgreSQL. Configure Kafka authentication and network-policy egress for your environment. Bundled PostgreSQL is enabled by default; an external database is also supported.

Configure registry credentials for every workload in the namespace. Upstream only attaches imagePullSecrets to the Kates Deployment. For a new evaluation namespace, attach the pull secret to the default service account used by PostgreSQL and the jobs:

kubectl patch serviceaccount default --namespace kates \
  --type merge --patch '{"imagePullSecrets":[{"name":"cgr-pull-secret"}]}'

Sample installation with bundled PostgreSQL

This is a sample value set for evaluation, not a production-ready configuration. Save the following as sample-values.yaml, replacing the database password and Kafka address for your environment:

imagePullSecrets:
  - name: cgr-pull-secret
kafka:
  bootstrapServers: kafka.kafka.svc.cluster.local:9092
postgresql:
  enabled: true
  auth:
    password: REPLACE_WITH_DATABASE_PASSWORD

The chart binds PostgreSQL and its backup client to PostgreSQL 16. This sample keeps the upstream PostgreSQL security-context defaults.

helm install kates oci://cgr.dev/ORGANIZATION/charts/kates \
  --namespace kates \
  --values sample-values.yaml

The sample assumes Kafka is reachable in namespace kafka on port 9092, matching the default network-policy egress. Adjust networkPolicy.kafka.port for another port and add networkPolicy.egressRules for brokers outside that namespace; the upstream Kafka namespace selector is hardcoded to kafka. API-key authentication remains enabled; the chart generates a key when none is supplied.

External database alternative

For an existing PostgreSQL database, replace the postgresql block in the sample above with the following and add externalDatabase. Replace the hostname, database, and username for your environment:

postgresql:
  enabled: false
externalDatabase:
  enabled: true
  host: postgres.database.svc.cluster.local
  port: 5432
  database: kates
  username: kates
  existingSecret: kates-database-credentials

The chart imports the existing Secret directly as environment variables. Supply both Quarkus credential keys; the advertised passwordKey value does not remap them:

kubectl create secret generic kates-database-credentials --namespace kates \
  --from-literal=QUARKUS_DATASOURCE_USERNAME=kates \
  --from-literal=QUARKUS_DATASOURCE_PASSWORD=REPLACE_WITH_DATABASE_PASSWORD

This is also a connection example, not a production deployment recipe. Configure database availability, backups, TLS, credentials, and network access for your environment. Upstream recommends an external managed cluster for production HA; bundled PostgreSQL is a single-instance StatefulSet. Neither database choice requires enabling the optional migration hook: the application runs Flyway migrations at startup for both.

FIPS

Select the chart's -fips version tag with helm install --version <chart-version>-fips and retain the image's Bouncy Castle module path when setting jvm.options. Add this to your values, adjusting heap sizes to your resource limits:

jvm:
  options: >-
    --module-path=/usr/share/java/bouncycastle-fips
    -Djavax.net.ssl.trustStoreType=FIPS
    -Xms512m -Xmx2560m -XX:+UseZGC -XX:+ZGenerational

Use Kafka TLS/SASL settings and BCFKS truststores appropriate to your environment. The TCP readiness helper is shared between variants and performs no cryptographic operations.

Optional pre-upgrade migration hook

migration.enabled defaults to false. It is not required for normal startup migrations or for production releases. If you choose to run the separate pre-upgrade hook, its upstream command assumes /deployments/quarkus-run.jar; the Chainguard image uses /app/quarkus-run.jar.

The following sample overrides that command and waits for Quarkus startup after Flyway completes. The hook does not mount API-key or Kafka secrets, so this short-lived process binds HTTP to loopback, disables its own API authentication, and points Kafka at an unused loopback port. These settings do not change the application Deployment's authentication or Kafka connection. Add the complete block to your values only when enabling this hook:

migration:
  enabled: true
  command:
    - sh
    - -ec
    - |
      : > /tmp/migration.log
      trap 'cat /tmp/migration.log' EXIT
      java -Xms128m -Xmx384m \
        -Dquarkus.flyway.migrate-at-start=true \
        -Dquarkus.flyway.baseline-on-migrate=true \
        -Dquarkus.http.host=127.0.0.1 \
        -Dkates.api.security-enabled=false \
        -Dkates.kafka.bootstrap-servers=127.0.0.1:1 \
        -Dkates.kafka.security.protocol=PLAINTEXT \
        -Dquarkus.scheduler.enabled=false \
        -Dkates.chaos.orphan-recovery.enabled=false \
        -jar /app/quarkus-run.jar > /tmp/migration.log 2>&1 &
      pid=$!
      export pid
      timeout 180 sh -ec '
        until grep -Fq "Listening on: http://127.0.0.1:8080" /tmp/migration.log; do
          kill -0 "$pid"
          sleep 1
        done
      '
      kill "$pid"
      wait "$pid" || test "$?" -eq 143

Other optional jobs and Helm tests

Backup is disabled by default. backup.enabled=true only runs with bundled PostgreSQL; enable backup.persistence.enabled to retain output. External-database backups are managed separately.

Keep cleanup.enabled=false (the default): the upstream cleanup job omits API-key authentication and requests COMPLETED, which the application does not recognize (DONE is the completed status). Substituting a Chainguard image does not correct that command.

The three upstream helm test hooks use curlimages/curl:8.7.1, not Chainguard images, and require access to that registry.

See the upstream chart documentation for other configuration options.