Productify

Appearance

Nomad Deployment Guide ​

This guide explains how to use the ProductifyFW CLI to manage Nomad deployments efficiently.

Overview ​

The pfy nomad commands streamline the deployment workflow by:

  • Automatically updating Docker image versions in Nomad HCL files
  • Validating job configurations before deployment
  • Integrating with project version management
  • Providing dry-run and plan-only modes for safety

Prerequisites ​

1. Install Nomad CLI ​

The pfy nomad commands require the Nomad CLI to be installed and accessible:

bash
# macOS
brew install nomad

# Linux
wget https://releases.hashicorp.com/nomad/1.7.0/nomad_1.7.0_linux_amd64.zip
unzip nomad_1.7.0_linux_amd64.zip
sudo mv nomad /usr/local/bin/

# Verify installation
nomad version

2. Configure Nomad Connection ​

Set up Nomad connection via environment variables:

bash
export NOMAD_ADDR=http://nomad.example.com:4646
export NOMAD_TOKEN=your-nomad-token  # If ACLs are enabled

Or create a Nomad configuration file at ~/.nomad.d/config.hcl.

3. Initialize Project Configuration ​

bash
# Initialize project configuration
pfy init --name my-project --language go

# This creates project.yaml with CI/registry configuration

4. (Optional) Configure Nomad File Path ​

Add the nomad_file path to your project.yaml to avoid specifying it in every command:

yaml
ci:
  type: github
  language: go
  registry: ghcr.io
  image_name: my-project
  nomad_file: nomad/manager.nomad # Path to your Nomad job file

With this configured, you can run:

bash
pfy nomad deploy --use-project-version
# Instead of:
pfy nomad deploy -f nomad/manager.nomad --use-project-version

Basic Deployment Workflow ​

1. Update Version ​

First, update your project version:

bash
# Bump patch version (e.g., 1.2.3 -> 1.2.4)
pfy version bump --part patch

# Or set a specific version
pfy version set --version 1.3.0

# Check current version
pfy version show

2. Deploy to Nomad ​

Deploy using the project version:

bash
pfy nomad deploy -f path/to/job.nomad --use-project-version

This will:

  1. Read version from project.yaml
  2. Update the Docker image tag in the Nomad HCL file
  3. Validate the job file
  4. Deploy the job to Nomad

Advanced Usage ​

Manual Image and Tag ​

Specify image and tag explicitly:

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

Update Tag Only ​

Update just the tag while keeping the existing image name:

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

Safe Deployment with Planning ​

Preview changes before deploying:

bash
# Plan the deployment
pfy nomad deploy -f manager.nomad --tag v1.2.3 --plan-only

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

Dry Run ​

See what would change without modifying anything:

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

Skip Validation ​

If you're confident in your HCL file:

bash
pfy nomad deploy -f manager.nomad --tag v1.2.3 --skip-validation

Multi-Environment Deployments ​

Directory Structure ​

Organize Nomad files by environment:

nomad/
├── dev/
│   ├── manager.nomad
│   └── optimizer.nomad
├── staging/
│   ├── manager.nomad
│   └── optimizer.nomad
└── prod/
    ├── manager.nomad
    └── optimizer.nomad

Development Environment ​

bash
# Deploy latest development build
pfy nomad deploy -f nomad/dev/manager.nomad --tag dev-latest

Staging Environment ​

bash
# Promote a specific version to staging
pfy nomad deploy -f nomad/staging/manager.nomad --tag v1.2.3

Production Environment ​

bash
# Always use plan-only first in production
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.3 --plan-only

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

CI/CD Integration ​

GitHub Actions Example ​

yaml
name: Deploy to Nomad

on:
  push:
    tags:
      - "v*"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install pfy CLI
        run: |
          curl -LO https://github.com/ProductifyFW/cli/releases/latest/download/pfy-linux-amd64
          chmod +x pfy-linux-amd64
          sudo mv pfy-linux-amd64 /usr/local/bin/pfy

      - name: Set up Nomad
        env:
          NOMAD_ADDR: ${{ secrets.NOMAD_ADDR }}
          NOMAD_TOKEN: ${{ secrets.NOMAD_TOKEN }}
        run: |
          # Extract version from tag
          VERSION=${GITHUB_REF#refs/tags/v}

          # Deploy to staging
          pfy nomad deploy -f nomad/staging/manager.nomad --tag v$VERSION

      - name: Deploy to Production
        if: github.event_name == 'release'
        env:
          NOMAD_ADDR: ${{ secrets.NOMAD_ADDR }}
          NOMAD_TOKEN: ${{ secrets.NOMAD_TOKEN }}
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          pfy nomad deploy -f nomad/prod/manager.nomad --tag v$VERSION

GitLab CI Example ​

yaml
deploy:staging:
  stage: deploy
  script:
    - VERSION=$(cat .version)
    - pfy nomad deploy -f nomad/staging/manager.nomad --tag v$VERSION
  environment:
    name: staging
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - VERSION=$(cat .version)
    - pfy nomad deploy -f nomad/prod/manager.nomad --tag v$VERSION --plan-only
    # Requires manual approval in GitLab
  environment:
    name: production
  only:
    - tags
  when: manual

Workflow Examples ​

Complete Release Workflow ​

bash
# 1. Bump version
pfy version bump --part minor

# 2. Commit version change
git add project.yaml
git commit -m "Bump version to $(pfy version show)"

# 3. Create git tag
git tag v$(pfy version show)
git push && git push --tags

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

# 5. Test staging...

# 6. Deploy to production (with plan)
pfy nomad deploy -f nomad/prod/manager.nomad --use-project-version --plan-only

# 7. Review plan, then deploy
pfy nomad deploy -f nomad/prod/manager.nomad --use-project-version

Hotfix Workflow ​

bash
# 1. Create hotfix branch
git checkout -b hotfix/critical-fix

# 2. Make fixes and bump patch version
pfy version bump --part patch

# 3. Deploy directly to production with planning
pfy nomad deploy -f nomad/prod/manager.nomad --use-project-version --plan-only

# 4. After review, deploy
pfy nomad deploy -f nomad/prod/manager.nomad --use-project-version

# 5. Merge back to main
git checkout main
git merge hotfix/critical-fix

Rollback Workflow ​

bash
# 1. Find previous version
git log --oneline project.yaml

# 2. Deploy previous version
pfy nomad deploy -f nomad/prod/manager.nomad --tag v1.2.2

# Or update project.yaml and use project version
pfy version set --version 1.2.2
pfy nomad deploy -f nomad/prod/manager.nomad --use-project-version

Troubleshooting ​

Nomad Connection Issues ​

bash
# Verify Nomad connection
nomad status

# Check environment variables
echo $NOMAD_ADDR
echo $NOMAD_TOKEN

Validation Failures ​

bash
# Validate the job file
pfy nomad validate -f manager.nomad

# Or use Nomad directly
nomad job validate manager.nomad

Image Not Found ​

Ensure the image exists in your registry:

bash
# Check if image:tag exists
docker pull ghcr.io/productifyfw/manager:v1.2.3

Deployment Failures ​

bash
# Check Nomad job status
nomad job status manager

# View allocations
nomad alloc logs <alloc-id>

# Check events
nomad alloc status <alloc-id>

Best Practices ​

1. Always Plan Before Production ​

bash
# Never deploy to production without planning first
pfy nomad deploy -f nomad/prod/app.nomad --tag v1.0.0 --plan-only

2. Use Project Version Management ​

bash
# Keep versions in sync with project.yaml
pfy nomad deploy -f job.nomad --use-project-version

3. Tag Docker Images Properly ​

bash
# Use semantic versioning for tags
pfy nomad deploy -f job.nomad --tag v1.2.3

# Avoid using 'latest' in production

4. Separate Environment Configurations ​

Maintain separate Nomad job files for each environment with appropriate resource allocations and constraints.

5. Automate in CI/CD ​

Integrate deployment commands into your CI/CD pipeline for consistency and traceability.

6. Document Deployments ​

bash
# Use git tags and commit messages
git tag -a v1.2.3 -m "Release v1.2.3: New features and bug fixes"

See Also ​