harmony/docs/guides/fleet-podman-deployments.md

Fleet Podman deployments

Fleet Deployment resources carry a ReconcileScore. PodmanV0 supports one optional init container followed by one or more long-running services.

apiVersion: fleet.nationtech.io/v1alpha1
kind: Deployment
metadata:
  name: analysis-api
spec:
  allowedGroups: [lab]
  targetSelector:
    matchLabels:
      role: analyzer
  rollout:
    strategy: Immediate
  score:
    type: PodmanV0
    data:
      init_container:
        name: analysis-migrate
        image: registry.example.com/analysis-migrate@sha256:<digest>
        ports: []
        env: []
        secret_env: []
        volumes:
          - host_path: /var/lib/analysis
            container_path: /data
            read_only: false
        restart_policy: "no"
      services:
        - name: analysis-api
          image: registry.example.com/analysis-api@sha256:<digest>
          ports: ["8080:8080"]
          env: []
          secret_env: []
          volumes:
            - host_path: /var/lib/analysis
              container_path: /data
              read_only: false
          restart_policy: unless-stopped

Immediate starts the rollout without operator approval. When any matched device has the canary=true label, those devices must converge before the same revision is released to the remaining frozen targets.

The target set and canary membership are frozen for the revision. A failed canary prevents release to non-canaries. Fleet does not roll back canaries that already converged, and it has no percentage, batch-size, concurrency, pause, or manual-approval setting.

allowedGroups is enforced only when the operator has a group source. The public production composition does not currently wire one, so it fails closed and matches no devices until a private composition provides group membership.

The agent preflights names, ports, ownership, and images before changing the deployment. It then runs init_container with restart policy no and waits for it to exit. Exit code zero allows service reconciliation to continue. Any other exit code marks the deployment failed and leaves services that have not yet been reconciled untouched. The next reconciliation pass retries the failed init container.

The completed init container remains in Podman as the durable completion marker. Reconciliation skips it while the complete resolved score is unchanged. Changing any score field, including a regular service field, replaces and reruns the init container before reconciling services. Resolved secret values are part of the score revision, but the agent does not watch the secret source for changes. Init containers must be idempotent. Removing the Deployment removes both the init container and its services.

Container replacement and Deployment removal ask Podman to stop each running container with a 30-second timeout, then force-remove it. Fleet does not wait indefinitely for graceful shutdown; applications must finish termination work within that timeout.

init_container uses the same PodmanService fields as a service. Secret references are resolved before Podman receives the definition. The runtime always overrides its restart policy to no; setting another value does not make an init container long-running. Its ports list must be empty because an init container cannot publish host ports.