Skip to main content

Kubernetes quickstart

The public donkeyfleet-chart OCI artifact deploys the application, Service, ConfigMap, ServiceAccount, optional Vault Kubernetes-auth wiring, and optional single-replica PostgreSQL. It creates no ingress by default. Production installations should use external OIDC, Vault, and PostgreSQL services.

Prepare the namespace and Secret​

kubectl create namespace donkeyfleet

Provide a Secret containing db-username, db-password, and oidc-client-secret. For more than one app replica, also provide a stable value of at least 32 characters for the session-encryption key named below.

Create a private values.yaml:

image:
  repository: registry.example.com/donkeyfleet/donkeyfleet
  tag: "1.0.0"
  pullPolicy: IfNotPresent
# imagePullSecrets: [{name: registry-pull}]   # only for a private image

config:
  oidc:
    issuer: https://identity.example.com/realms/donkeyfleet
    clientId: donkeyfleet
    sessionEncryptionSecretKey: oidc-encryption-secret
  vault:
    address: https://vault.example.com/
    kubernetes:
      role: kubernetes-donkeyfleet
      authMountPath: kubernetes-donkeyfleet
  database:
    url: jdbc:postgresql://postgres.example.com:5432/donkeyfleet?sslmode=require
  reconcile:
    interval: 5m
    provisioningPollInterval: 15s
    dryRun: true
    dryRunUiOverride: false

secret:
  create: false
  existingSecret: donkeyfleet-secrets

postgres:
  enabled: false

The image and chart have independent versions. image.tag selects the application; Helm --version selects deployment templates and defaults.

Install the chart​

helm install donkeyfleet \
  oci://registry-1.docker.io/saragihruben29/donkeyfleet-chart \
  --version 1.0.1 \
  --namespace donkeyfleet \
  --create-namespace \
  --values values.yaml

The chart defaults nameOverride to donkeyfleet, so the dedicated donkeyfleet-chart artifact still renders normal donkeyfleet resource names.

Vault Kubernetes authentication​

The application ServiceAccount must be included in the Vault role's bound ServiceAccounts. Check vault read auth/<mount>/config:

  • With token_reviewer_jwt_set=true, the dedicated reviewer ServiceAccount performs TokenReview.
  • With token_reviewer_jwt_set=false and disable_local_ca_jwt=true, set vaultKubernetesAuth.appAuthDelegator=true; the application token must perform TokenReview.
  • Enable vaultKubernetesAuth.legacyToken.enabled only when the Vault method requires a legacy ServiceAccount token instead of the projected pod token.

Availability​

One replica is sufficient for reconciliation. Multiple replicas improve web availability while a PostgreSQL advisory lock keeps reconciliation single-writer. They do not require sticky sessions. Use one shared session-encryption key and, for HA, configure:

replicaCount: 3
updateStrategy:
  type: RollingUpdate
  rollingUpdate: {maxUnavailable: 0, maxSurge: 1}
podDisruptionBudget:
  enabled: true
  minAvailable: 1

Use RollingUpdate only when application migrations are backward-compatible with the previous version. Spread pods with your platform's affinity or topology constraints; the chart does not assume node labels.

Platform responsibilities​

Provide TLS termination, network policy, the ingress controller or Gateway, durable database backups, and monitoring. The chart can render a standard Ingress or Gateway API HTTPRoute but does not install their controllers.

Confirm /q/health/live, /q/health/ready, and /q/metrics, then complete the first dry-run.