Skip to content

Always up-to-date GitOps

Always up-to-date GitOps extends Classic GitOps by automatically capturing external changes through discovery and synchronization. You still work with reconcile as your primary mode, but formae can discover and synchronize changes made outside your code. This is how the reality looks like in many setups, and formae helps adapt to the reality.

In this workflow, your forma remains the source of truth, but formae actively tracks changes made outside your code and gives you tools to bring them under management.

Prerequisites: Read Classic GitOps first to understand reconcile mode and basic workflows.

Enabling discovery and synchronization

To use this workflow, enable discovery and synchronization in your configuration:

agent {
    discovery {
        enabled = true
        interval = 10.min
    }

    synchronization {
        enabled = true
        interval = 5.min
    }
}

How external changes are handled

Discovery

formae periodically scans your AWS account for resources that aren't yet under management. These discovered resources are tracked internally but remain unmanaged until you explicitly bring them under management. This allows you to:

  • Gradually adopt formae in existing environments
  • Work alongside other infrastructure tools
  • See all infrastructure even if not created by formae

Learn more in Discovery.

Synchronization

formae continuously monitors your managed resources for external changes (ClickOps, other tools, manual changes). When changes are detected, they're automatically synchronized into formae's state. This ensures formae always has an accurate view of your infrastructure.

Learn more in Synchronization.

Working with unmanaged resources

Extract resources to see what exists

# Extract all unmanaged resources
formae extract --query 'managed:false' ./unmanaged-resources.pkl

# Extract specific unmanaged resource types
formae extract --query 'managed:false type:AWS::S3::Bucket' ./buckets.pkl

# Extract resources from a specific stack
formae extract --query 'stack:my-stack' ./stack-resources.pkl

The extract command creates a forma file with the discovered resources:

// Generated by formae extract
forma {
    new bucket.Bucket {
        label = "my-production-bucket"
        bucketName = "my-production-bucket"
        // ... all current properties
    }
}

Place extracted resources under management

  1. Review the extracted forma file - Check the resources that were discovered
  2. Edit the file - Add a stack label and description (required for management): 
    local myStack = new formae.Stack {
    label = "discovered-resources"
    description = "Resources discovered from existing infrastructure"
}
myStack

forma {
    new bucket.Bucket {
        label = "my-production-bucket"
        bucketName = "my-production-bucket"
        // ... all current properties
    }
}
  3. Apply to put resources under management: 
    # Apply extracted resources (soft reconcile - warns when a discrepancy exists between your forma definition
# and the external state - won't overwrite changes when a difference is detected)
formae apply --mode reconcile extracted-resources.pkl

# Force reconcile - overwrites external changes
formae apply --mode reconcile --force extracted-resources.pkl

Patch mode for minimal blast radius

Patch mode only creates or updates, it never destroys. Perfect for:

  • Adding new resources to existing infrastructure
  • Quick fixes and additions
  • Emergency changes where you need minimal blast radius
  • Team-specific additions without affecting shared infrastructure
  • Wide, but small changes on many resources, for example version updates or security patches

Additive changes with patch mode

// patch-add-monitoring.pkl
amends "@formae/forma.pkl"
import "@formae/formae.pkl"
import "@aws/logs/loggroup.pkl"

forma {
  // This will be added to existing infrastructure
  new loggroup.LogGroup {
    logGroupName = "/aws/lambda/my-function"
    retentionInDays = 14
  }
}

Apply with patch mode: 

formae apply --mode patch patch-add-monitoring.pkl

When to use patch vs reconcile

Use reconcile mode for:

  • Holistic changes: Complete infrastructure updates
  • Structural changes: VPC changes, major refactoring
  • Cleanup: When you want formae to implicitly remove unused resources

Use patch mode for:

  • Additive changes: Adding new resources to existing infrastructure
  • Quick fixes: Emergency changes with minimal risk
  • Team workflows: Different teams adding their components
  • Gradual adoption: Incrementally bringing discovered resources under management

Handling synchronized changes

When external changes are detected on managed resources, formae will synchronize these changes into its state and allow you to extract and review the changes.

# Check agent stats to see managed vs unmanaged resources
formae status agent

# Extract managed resources and review any changes
formae extract --query "managed:true" ./current-state.pkl

When to use Always up-to-date GitOps

  • Mixed teams: Changes happen outside your infrastructure code (and they do happen)
  • Legacy migration: Gradually bringing existing infrastructure under management
  • Emergency changes: Need to handle urgent fixes made outside your workflow
  • Multi-tool environments: Working alongside other infrastructure tools for gradual migration or simply co-existence

Best practices

Regular maintenance

# Weekly: Extract and review unmanaged resources
formae extract --query "managed:false" ./weekly-discovery.pkl
# Review the file, then apply if needed
formae apply --mode reconcile weekly-discovery.pkl

# Monthly: Full reconciliation
formae extract --query "managed:true" ./changes.pkl
formae apply --mode reconcile changes.pkl

Complete workflow example

# Day-0: Deploy base infrastructure (reconcile mode)
formae apply --mode reconcile --watch main.pkl

# Day-1: Add monitoring (patch mode)
formae apply --mode patch --watch monitoring.pkl

# Day-10: Add team-specific resources (patch mode)
formae apply --mode patch --watch team-database.pkl

# Day-30: Full infrastructure update (reconcile mode)
formae apply --mode reconcile --watch main.pkl

# Day-35: Handle external changes (discovery + extract)
formae extract --query "managed:false" ./new-resources.pkl

# Review and edit the extracted file to add stack label
# Then apply
formae apply --mode reconcile --watch new-resources.pkl

What's next

You now understand how to use discovery and synchronization to work with existing infrastructure. Explore related concepts: