harmony/docs/guides/fleet-products.md

Fleet product line

Fleet has one domain and three jobs. They share CRDs, the agent protocol, and operator Scores. They do not share binaries, permission sets, or release cadence.

Domain (no UI):  Device, Deployment, agentUpgrade, operator
                 CRDs · agent protocol · Scores

Job	Who	How often	Identity	Surface
Operate	The tenant	Daily	Tenant Zitadel key → OpenBao ClusterAccess	harmony-fleet
Provision	NationTech, later the tenant	Rare	Installer / bootstrap kubeconfig, then tenant key	Tenant deploy crate (deploy_fleet_with_context)
Release	NationTech	Harmony cadence	Fleet bot → hub.nationtech.io/harmony/*	fleet/scripts/release.sh

Operate never publishes Harbor harmony/*. Release never patches a Device. Provision never looks like device upgrade. Application ship (tenant app images) is none of these three.

Operate

Inspect devices and pin them to a published version. Harbor is the catalog: the CLI takes --version / --arch, the domain resolves a digest-pinned Pin, and Tenant writes it. Tenants do not paste digests.

cargo run -p harmony-fleet-cli --bin harmony-fleet -- \
  device versions --arch aarch64

export HARMONY_ZITADEL_KEY_JSON  # tenant operate key, not the Fleet image bot

cargo run -p harmony-fleet-cli --bin harmony-fleet -- \
  --tenant detexion/harmony-fleet \
  device list

cargo run -p harmony-fleet-cli --bin harmony-fleet -- \
  --tenant detexion/harmony-fleet \
  device upgrade --name detexion-pi-arm64-01 \
  --version 0.6.7 --arch aarch64

--tenant is the OpenBao path (detexion/harmony-fleet) holding ClusterAccess. device versions / operator versions do not need a tenant key. Upgrade prints the pin that was written. Default log level is warn; RUST_LOG=info logs resolved pins.

Also: deployment list, operator status, operator versions, operator upgrade --version (catalog fills operator and callout images for that tag).

OPENBAO_JWT_ROLE defaults to nationtech-cloud-tenants. The provision identity uses a different role; set the env var if you operate with that key.

Release

Build and push operator, NATS callout, and fleet-agent images. Print digests.

export HARMONY_ZITADEL_KEY_JSON  # Fleet bot, not a tenant key

fleet/scripts/release.sh --agent-version 0.6.8 --agent-arch aarch64
fleet/scripts/release.sh --control-version 0.6.8

OpenBao tree: harmony/harmony-fleet / RegistryCredentials. Fallback: REGISTRY_USER / REGISTRY_TOKEN. This script does not take --device and does not deploy a tenant control plane.

Provision

Install or replace the operator in a tenant cluster, using already published image digests from Release.

export HARMONY_ZITADEL_KEY_JSON  # tenant key that can read ClusterAccess

cargo run --release -- \
  deploy --context detexion-harmony-fleet --tag 0.6.8 \
  --image operator=hub.nationtech.io/harmony/harmony-fleet-operator@sha256:... \
  --image callout=hub.nationtech.io/harmony/harmony-nats-callout@sha256:...

Run that from the tenant crate (compiled Context: Kubernetes namespace, OpenBao path, domain). First install still needs CRDs and provision_fleet_tenant with a cluster-admin kubeconfig — see Control-plane operations.

ClusterAccess is a kubeconfig stored in the tenant OpenBao namespace. It is not a Cargo manifest. --deploy-manifest on older release.sh invocations meant “path to the tenant crate’s Cargo.toml”; that mixing is retired.