Version Cooldown

​

Why Use Version Cooldown?

• Reduce deployment frequency - Batch multiple rapid releases into fewer deployments
• Decrease infrastructure load - Avoid constant rolling updates from CI/CD pipelines
• Improve stability - Give each deployment time to prove itself before the next
• Save resources - Reduce compute spent on deployment overhead

​

Configuration

resource "ctrlplane_policy" "batch_deployments" {
  name     = "Batch Deployments"
  selector = "environment.name == 'production'"

  version_cooldown {
    duration = "1h"
  }
}

curl -X POST https://api.ctrlplane.com/v1/workspaces/{workspaceId}/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Batch Deployments",
    "selector": "environment.name == '\''production'\''",
    "rules": [
      {
        "versionCooldown": {
          "intervalSeconds": 3600
        }
      }
    ]
  }'

​

Properties

​

How It Works

1. Find reference version: The currently deployed or in-progress version (in-progress takes precedence)
2. Calculate elapsed time: Time since the reference version was created (using current time)
3. Apply cooldown: If elapsed time >= interval, allow any version; otherwise, deny

​

Example Timeline

Version Created:  v1.0 ────── v1.1 ── v1.2 ── v1.3 ────── v1.4
                  12:00       12:15   12:20   12:25       13:00

With intervalSeconds: 3600 (1 hour)
Currently deployed: v1.0 (created 12:00)

At 12:30 (30min elapsed since v1.0):
  Candidate v1.3 (created 12:25): DENIED - only 30min elapsed (need 60min)
  Candidate v1.2 (created 12:20): DENIED - only 30min elapsed
  Candidate v1.1 (created 12:15): DENIED - only 30min elapsed

At 13:05 (65min elapsed since v1.0):
  Candidate v1.3 (created 12:25): ALLOWED - 65min elapsed (>= 60min)
  Candidate v1.2 (created 12:20): ALLOWED - 65min elapsed
  Candidate v1.1 (created 12:15): ALLOWED - 65min elapsed
  Candidate v1.4 (created 13:00): ALLOWED - 65min elapsed

​

Common Patterns

​

Hourly Batching

resource "ctrlplane_policy" "hourly_deployments" {
  name     = "Hourly Deployments"
  selector = "environment.name == 'production'"

  version_cooldown {
    duration = "1h"
  }
}

{
  "name": "Hourly Deployments",
  "selector": "environment.name == 'production'",
  "rules": [
    { "versionCooldown": { "intervalSeconds": 3600 } }
  ]
}

​

Per-Environment Cooldown

resource "ctrlplane_policy" "staging_cooldown" {
  name     = "Staging Cooldown"
  selector = "environment.name == 'staging'"

  version_cooldown {
    duration = "15m"
  }
}

resource "ctrlplane_policy" "production_cooldown" {
  name     = "Production Cooldown"
  selector = "environment.name == 'production'"

  version_cooldown {
    duration = "1h"
  }
}

[
  {
    "name": "Staging Cooldown",
    "selector": "environment.name == 'staging'",
    "rules": [
      { "versionCooldown": { "intervalSeconds": 900 } }
    ]
  },
  {
    "name": "Production Cooldown",
    "selector": "environment.name == 'production'",
    "rules": [
      { "versionCooldown": { "intervalSeconds": 3600 } }
    ]
  }
]

​

Combined with Other Rules

resource "ctrlplane_policy" "production_controlled_release" {
  name     = "Production Controlled Release"
  selector = "environment.name == 'production'"

  version_cooldown {
    duration = "30m"
  }

  any_approval {
    min_approvals = 1
  }

  gradual_rollout {
    rollout_type        = "linear"
    time_scale_interval = 300
  }
}

​

With Deployment Windows

resource "ctrlplane_policy" "controlled_production" {
  name     = "Controlled Production"
  selector = "environment.name == 'production'"

  deployment_window {
    rrule            = "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0"
    duration_minutes = 480
    timezone         = "America/New_York"
  }

  version_cooldown {
    duration = "2h"
  }
}

​

Weekly Scheduled Deployments

resource "ctrlplane_policy" "monday_deployments" {
  name     = "Monday Deployments"
  selector = "deployment.name == 'datadog-agent'"

  deployment_window {
    rrule            = "FREQ=WEEKLY;BYDAY=MO;BYHOUR=0;BYMINUTE=0"
    duration_minutes = 1440
    timezone         = "America/New_York"
    allow_window     = true
  }

  version_cooldown {
    duration = "120h"
  }

  gradual_rollout {
    rollout_type        = "linear-normalized"
    time_scale_interval = 82800
  }
}

​

Behavior Details

​

Version Selection

1. Ctrlplane tries the next older version
2. This continues until a qualifying version is found
3. If no versions qualify, the release target waits

​

Same Version Redeploys

• Manual re-runs of failed deployments
• Rollback-and-redeploy workflows
• Configuration-only changes - Deploy the same version with updated configuration immediately, bypassing cooldown

​

Urgent Deployments

• Same-version redeploy: If the urgent change uses the same version ID, it automatically bypasses cooldown
• Policy Skip: Create a PolicySkip to bypass cooldown for a specific version. This allows urgent deployments while maintaining cooldown for regular releases

​

In-Progress Deployments

• Prevents deploying a newer version while one is still rolling out
• Ensures sequential deployments respect the interval

​

Best Practices

​

Interval Guidelines

​

Recommendations

• ✅ Start with shorter intervals and increase as needed
• ✅ Use longer intervals for production vs staging
• ✅ Combine with gradual rollouts for safer deployments
• ✅ Monitor deployment frequency to tune intervals
• ✅ Use same-version redeploys for urgent configuration changes
• ✅ Use PolicySkip for urgent deployments that need to bypass cooldown
• ❌ Don’t set intervals so long that critical fixes are delayed
• ❌ Don’t use cooldown on environments that need immediate updates
• ⚠️ Ensure deployment windows are long enough for gradual rollouts to complete

​

Next Steps

• Policies Overview - Learn about policy structure
• Gradual Rollouts - Control deployment pace
• Deployment Window - Time-based deployment control