deploy diff

pfy deploy diff checks whether a deployment has drifted. It renders the Nomad job fresh from the spec in the Manager and compares it with two things: the job file committed in your repository (repo drift) and the job running in the cluster (cluster drift). Use it locally before a deploy, or in CI with --exit-code to fail a pipeline on drift.

Synopsis

pfy deploy diff [target flags] [--out <file>] [--exit-code]

Description

Because the spec lives in the Manager and the job file in git is generated from it, a plain git diff cannot tell you whether the file is current. pfy deploy diff renders the job fresh from the current spec and compares:

• repo: the freshly rendered job against the committed artifact (project.yaml ci.nomad_file, or --out), shown as a compact -/+ line diff
• cluster: the current spec hash against the pfy_spec_hash meta stamped on the running Nomad job (read via nomad job inspect)

pfy deploy has only this one subcommand; the command that performs a deploy is pfy nomad deploy.

Flags

In addition to the shared targeting flags (--env, --app, --deployment-id, --name, --tenant, --service) and render flags (--tag, --use-project-version, --region, --optimizer-endpoint):

Flag	Short	Description
--out		Committed artifact path to diff against (defaults to project.yaml ci.nomad_file). No short form
--exit-code		Exit 1 when drift is detected or when the cluster side could not be verified (use in CI). Without it the command always exits 0 after a successful read

Examples

Clean

pfy deploy diff --env prod --tag v1.2.3

repo:    clean — nomad/myapp.nomad.hcl matches the rendered spec
cluster: clean — running job "myapp" is at spec 3f9a2c…
No drift: spec 3f9a2c… matches the committed artifact and the running job.

Drift

pfy deploy diff --env prod --tag v1.2.3

repo:    DRIFT — nomad/myapp.nomad.hcl differs from the rendered spec:
    - memory = 256
    + memory = 512
cluster: DRIFT — running job "myapp" is at spec 9c1d0e… but the current spec is 3f9a2c…

Drift detected. Run `pfy nomad deploy --env prod` to reconcile (the spec is the source of truth; hand edits are overwritten).

In CI

# Fail the pipeline when the committed artifact or the cluster lags the spec
pfy --ci deploy diff --env prod --use-project-version --exit-code

Pass the same --tag your deploys use: the tag is part of the rendered artifact, so a mismatched tag reads as repo drift.

What each verdict means

Line	Verdict	Meaning
repo	DRIFT — <file> does not exist yet	No committed artifact; run pfy nomad render to create it
repo	(no committed artifact path…)	Neither ci.nomad_file nor --out set; repo drift is not checked
cluster	job … is not running (or carries no pfy_spec_hash)	Nothing to compare: jobs deployed before spec stamping, or not yet deployed
cluster	unknown — could not verify: <error>	nomad job inspect failed (Nomad unreachable, ACLs), so the cluster side was not verified. With --exit-code this exits 1 (drift could not be verified)

See Also

• nomad - Render/deploy (reconciles the drift)
• deployment - Edit the spec that is the source of truth
• Generated Artifacts - The rendering model