Productify

Appearance

Nomad Deployment Commands ​

The Nomad deployment commands manage Nomad job deployments.

Jobs are rendered from a deployment spec (Wave 3)

Since the Wave 3 release train, pfy nomad render renders a full Nomad job from the deployment spec on the Manager's Deployment entity, and pfy nomad deploy runs render → nomad job validate → nomad job plan → nomad job run. The in-place image/tag rewrite documented below is the legacy path, kept behind --legacy-rewrite for one minor release and warning loudly. New installs should render from the spec — see Generated Artifacts and pfy deployment get|set.

Overview ​

The pfy nomad command group provides utilities for:

  • Updating Docker image references in Nomad HCL files
  • Validating Nomad job configurations
  • Planning job changes
  • Deploying jobs to Nomad clusters

These commands integrate with the CLI's version management to streamline deployment workflows.

Commands ​

pfy nomad deploy ​

Update image/tag in a Nomad HCL file and deploy the job.

Usage:

bash
pfy nomad deploy -f <file> [options]

Flags:

  • -f, --file - Path to the Nomad HCL file (uses nomad_file from project.yaml if not specified)
  • -i, --image - Docker image name (e.g., ghcr.io/productifyfw/manager)
  • -t, --tag - Docker image tag/version
  • --use-project-version, --pv - Use version from project.yaml as the image tag
  • --plan-only - Only run nomad job plan without deploying
  • --skip-validation - Skip the nomad job validate step
  • --dry-run - Show what would be changed without modifying files or deploying

Examples:

Deploy with a specific tag:

bash
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3

Deploy using the version from project.yaml:

bash
pfy nomad deploy -f manager/nomad/manager.nomad --use-project-version

If you've set nomad_file in project.yaml, you can omit the -f flag:

bash
# Requires nomad_file configured in project.yaml
pfy nomad deploy --use-project-version

Update both image and tag:

bash
pfy nomad deploy -f manager/nomad/manager.nomad \
  --image ghcr.io/productifyfw/manager \
  --tag v1.2.3

Plan before deploying:

bash
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3 --plan-only

Preview changes without applying:

bash
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3 --dry-run

Workflow:

  1. Updates the image reference in the HCL file
  2. Validates the job file (unless --skip-validation)
  3. Runs nomad job plan (if --plan-only) or nomad job run

pfy nomad update-image ​

Update only the image/tag in a Nomad HCL file without deploying.

Usage:

bash
pfy nomad update-image -f <file> [options]

Flags:

  • -f, --file (required) - Path to the Nomad HCL file
  • -i, --image - Docker image name
  • -t, --tag - Docker image tag/version
  • --use-project-version, --pv - Use version from project.yaml as the image tag

Examples:

Update only the tag:

bash
pfy nomad update-image -f manager/nomad/manager.nomad --tag v1.2.3

Update using project version:

bash
pfy nomad update-image -f manager/nomad/manager.nomad --use-project-version

Interpolated image references are skipped

An image line built from a variable — image = "${IMAGE_NAME}:${TAG}" — cannot be rewritten without destroying the interpolation, so deploy and update-image leave it byte-for-byte untouched and report it:

Skipped job.nomad:5: image = "${IMAGE_NAME}:${TAG}" interpolates a variable; left unchanged
  rewriting it would destroy the interpolation; set the tag through the job's variable instead (nomad job run -var ...) or use a job file with a literal image

Set the tag through the job's own variable (nomad job run -var ...) instead, or use a job file with a literal image reference. Other image lines in the same file are still updated normally, and --dry-run (on deploy) reports the same skip as [DRY RUN] Would skip ....

Registry ports are preserved: the tag is split on the last colon only when it follows the last slash, so localhost:5000/acme/app:1.0.0 updates to localhost:5000/acme/app:2.0.0.

pfy nomad validate ​

Validate a Nomad HCL job file.

Usage:

bash
pfy nomad validate -f <file>

Flags:

  • -f, --file (required) - Path to the Nomad HCL file

Example:

bash
pfy nomad validate -f manager/nomad/manager.nomad

This runs nomad job validate to check the job file syntax and configuration.

pfy nomad plan ​

Run nomad job plan on a HCL file to preview changes.

Usage:

bash
pfy nomad plan -f <file>

Flags:

  • -f, --file (required) - Path to the Nomad HCL file

Example:

bash
pfy nomad plan -f manager/nomad/manager.nomad

This shows what changes would be made to the Nomad cluster without actually applying them.

Integration with Version Management ​

The Nomad commands integrate seamlessly with the CLI's version management system:

bash
# Bump version in project.yaml
pfy version bump --part minor

# Deploy using the new version
pfy nomad deploy -f manager/nomad/manager.nomad --use-project-version

This workflow ensures consistency between your project version and deployed container versions.

Common Workflows ​

Simple Deployment ​

bash
# Update version
pfy version set --version 1.2.3

# Deploy to Nomad
pfy nomad deploy -f manager/nomad/manager.nomad --use-project-version

Safe Deployment with Planning ​

bash
# Update and plan
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3 --plan-only

# Review the plan output, then deploy
pfy nomad deploy -f manager/nomad/manager.nomad --tag v1.2.3

Multi-Environment Deployment ​

bash
# Development
pfy nomad deploy -f nomad/dev/manager.nomad --tag dev-latest

# Staging
pfy nomad deploy -f nomad/staging/manager.nomad --tag v1.2.3

# Production
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.3 --plan-only
# Review plan, then:
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.3

Prerequisites ​

  • Nomad CLI must be installed and accessible in your PATH
  • Nomad cluster must be configured (via environment variables or Nomad config)
  • Appropriate permissions to deploy jobs to the target Nomad cluster

See Also ​