Skip to content

GitOps Workflow for Policies

This guide explains how to manage Fulcrum policies using GitOps principles with version-controlled YAML files.

Overview

The Fulcrum CLI provides a complete policies-as-code workflow:

  • Export policies from Fulcrum to YAML files
  • Import policies from YAML files to Fulcrum
  • Validate policy files before deployment
  • Diff local changes against remote state

Policy File Format

Policies use a Kubernetes-style YAML format:

apiVersion: fulcrum.io/v1
kind: Policy
metadata:
  name: production-budget-limit
  description: Monthly budget limit for production agents
  labels:
    environment: production
    team: platform
spec:
  policy_type: budget
  priority: 10
  status: ACTIVE
  enabled: true
  rules:
    max_monthly_spend: 10000
    alert_threshold: 0.8
    hard_limit: true

Fields

Field Required Description
apiVersion Yes Must be fulcrum.io/v1
kind Yes Must be Policy
metadata.name Yes Unique policy name (alphanumeric, dashes, underscores)
metadata.description No Human-readable description
metadata.labels No Key-value labels for organization
spec.policy_type Yes One of: budget, rate_limit, content_filter, approval, custom
spec.priority No Evaluation order (higher = first), default 0
spec.status No One of: ACTIVE, INACTIVE, DRAFT
spec.enabled No Boolean, default true
spec.rules No Policy-specific rule configuration

Multiple Policies

Use a PolicyList to define multiple policies in one file:

apiVersion: fulcrum.io/v1
kind: PolicyList
items:
  - apiVersion: fulcrum.io/v1
    kind: Policy
    metadata:
      name: budget-limit
    spec:
      policy_type: budget
      rules:
        max_monthly_spend: 5000

  - apiVersion: fulcrum.io/v1
    kind: Policy
    metadata:
      name: rate-limit
    spec:
      policy_type: rate_limit
      rules:
        requests_per_minute: 100

CLI Commands

Export Policies

Export policies from Fulcrum to YAML files:

# Export all policies to stdout
fulcrum policies export

# Export all policies to a single file
fulcrum policies export --output policies.yaml

# Export to individual files in a directory
fulcrum policies export --output-dir ./policies/

# Export a specific policy
fulcrum policies export pol-abc123 --output my-policy.yaml

Validate Policies

Validate policy files without deploying:

# Validate a single file
fulcrum policies validate policy.yaml

# Validate all files in a directory
fulcrum policies validate ./policies/

# Strict mode (warnings become errors)
fulcrum policies validate --strict ./policies/

Import Policies

Import policies from YAML files:

# Dry-run to see what would be imported
fulcrum policies import --dry-run ./policies/

# Import new policies (skip existing)
fulcrum policies import ./policies/

# Import and update existing policies by name
fulcrum policies import --update ./policies/

Diff Policies

Compare local files with remote state:

# Show differences
fulcrum policies diff ./policies/

# Output:
# + new-policy (new, will be created)
# ~ existing-policy (modified)
#     status: ACTIVE → INACTIVE
#     rules: modified
# - old-policy (exists remotely, not in local files)

policies/
├── README.md
├── production/
│   ├── budget-limits.yaml
│   ├── rate-limits.yaml
│   └── content-filters.yaml
├── staging/
│   └── test-policies.yaml
└── shared/
    └── approval-workflows.yaml

GitOps Workflow

1. Initial Export

Start by exporting existing policies:

fulcrum policies export --output-dir ./policies/
git add policies/
git commit -m "chore: export existing policies"

2. Make Changes

Edit policy files in your preferred editor:

# policies/budget-limit.yaml
apiVersion: fulcrum.io/v1
kind: Policy
metadata:
  name: monthly-budget
spec:
  policy_type: budget
  rules:
    max_monthly_spend: 15000  # Increased from 10000

3. Validate Locally

fulcrum policies validate ./policies/

4. Preview Changes

fulcrum policies diff ./policies/

5. Create Pull Request

git checkout -b update-budget-limits
git add policies/
git commit -m "feat: increase monthly budget limit"
git push origin update-budget-limits

6. Deploy After Merge

After PR approval and merge:

fulcrum policies import --update ./policies/

Best Practices

Version Control

  • Store all policies in git
  • Use meaningful commit messages
  • Require PR reviews for policy changes
  • Use branch protection on main

Organization

  • Group policies by environment or function
  • Use consistent naming conventions
  • Document policy purposes in descriptions
  • Use labels for categorization

CI/CD Integration

  • Validate policies on every PR
  • Diff changes in PR comments
  • Auto-deploy on merge to main
  • Keep staging and production separate

Security

  • Review policy changes carefully
  • Don't store secrets in policy files
  • Use environment-specific configurations
  • Maintain audit trail via git history

Troubleshooting

Validation Errors

metadata.name: must be alphanumeric with dashes/underscores, max 100 chars
Fix: Use only letters, numbers, dashes, and underscores in names.

spec.status: must be one of: ACTIVE, INACTIVE, DRAFT
Fix: Use uppercase status values.

Import Conflicts

Skipped (exists): my-policy - use --update to modify
Fix: Add --update flag to modify existing policies.

Diff Shows Unexpected Changes

If diff shows changes you didn't make, someone may have modified policies directly in the UI. Re-export to sync:

fulcrum policies export --output-dir ./policies/
git diff  # Review changes

Next Steps