​

Policies

​

Building Confidence Through Policies

Development → QA → Staging → Production
     ↓          ↓       ↓          ↓
   (none)    smoke   integration  full
             tests     tests     gates

• Start simple, grow complex - Begin with basic health checks in QA, add integration tests in staging, require approvals and verification in production
• Catch issues early - Run smoke tests in QA to catch problems before they reach production
• Automate quality gates - Let verification results automatically determine if a release can proceed
• Reduce deployment anxiety - Know that every production deployment has passed through proven checks
• Customize per environment - Apply stricter rules where they matter most

​

Policy Structure

1. Name & Description - Identify and document the policy’s purpose
2. Selector - A CEL expression defining which release targets the policy applies to
3. Rules - One or more rules specifying behavior or requirements
4. Priority - Higher priority policies are evaluated first
5. Metadata - Arbitrary key-value pairs for organization

resource "ctrlplane_policy" "production_gates" {
  name        = "Production Gates"
  description = "Require approval and gradual rollout for production"
  priority    = 10
  enabled     = true

  selector = "environment.name == 'production'"

  any_approval {
    min_approvals = 1
  }

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

{
  "name": "Production Gates",
  "description": "Require approval and gradual rollout for production",
  "priority": 10,
  "enabled": true,
  "selector": "environment.name == 'production'",
  "rules": [
    {
      "anyApproval": { "minApprovals": 1 }
    },
    {
      "gradualRollout": {
        "rolloutType": "linear",
        "timeScaleInterval": 300
      }
    }
  ]
}

​

Policy Selectors

​

Environment Selector

environment.name == "production"
environment.name in ["staging", "production"]
environment.name.startsWith("prod-")
environment.metadata['tier'] == "critical"

​

Resource Selector

resource.kind == "Kubernetes"
resource.metadata['region'] == "us-east-1"
resource.name.contains("critical")

​

Deployment Selector

deployment.name == "api-service"
deployment.metadata['team'] == "platform"

​

Combined Selectors

environment.name == "production" && deployment.metadata['tier'] == "critical"

​

Policy Rules

​

Approval Rule

​

Environment Progression Rule

​

Gradual Rollout Rule

​

Deployment Dependency Rule

​

Deployment Window Rule

​

Version Cooldown Rule

​

Retry Rule

​

Version Selector Rule

​

Verification Rule

​

Terraform Provider Reference

​

REST API Reference

POST /v1/workspaces/{workspaceId}/policies

GET    /v1/workspaces/{workspaceId}/policies/{policyId}
PUT    /v1/workspaces/{workspaceId}/policies/{policyId}
DELETE /v1/workspaces/{workspaceId}/policies/{policyId}

GET /v1/workspaces/{workspaceId}/policies

​

Policy Evaluation

1. Finds matching policies - Evaluates the selector CEL expression against each release target
2. Merges rules - Combines rules from all matching policies
3. Applies rules - Enforces each rule type

​

Rule Interactions

• Approval + Gradual Rollout: The rollout start time is determined by when the approval was satisfied
• Environment Progression + Gradual Rollout: The rollout waits until progression criteria are met
• Deployment Window + Gradual Rollout: Allow windows push the rollout start to the window opening; deny windows pause the rollout
• Version Cooldown + Deployment Window: Both must be satisfied — cooldown determines which version, window determines when

​

Common Patterns

​

Environment Progression

resource "ctrlplane_policy" "staging_policy" {
  name     = "Staging Policy"
  selector = "environment.name == 'staging'"

  environment_progression {
    depends_on_environment_selector = "environment.name == 'qa'"
  }
}

resource "ctrlplane_policy" "production_policy" {
  name     = "Production Policy"
  selector = "environment.name == 'production'"

  any_approval {
    min_approvals = 1
  }

  environment_progression {
    depends_on_environment_selector = "environment.name == 'staging'"
    minimum_sock_time_minutes       = 30
  }

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

[
  {
    "name": "Staging Policy",
    "selector": "environment.name == 'staging'",
    "rules": [
      {
        "environmentProgression": {
          "dependsOnEnvironmentSelector": "environment.name == 'qa'"
        }
      }
    ]
  },
  {
    "name": "Production Policy",
    "selector": "environment.name == 'production'",
    "rules": [
      { "anyApproval": { "minApprovals": 1 } },
      {
        "environmentProgression": {
          "dependsOnEnvironmentSelector": "environment.name == 'staging'",
          "minimumSockTimeMinutes": 30
        }
      },
      {
        "gradualRollout": {
          "rolloutType": "linear",
          "timeScaleInterval": 300
        }
      }
    ]
  }
]

​

Critical Service Protection

resource "ctrlplane_policy" "critical_service_gates" {
  name     = "Critical Service Gates"
  selector = "deployment.metadata['tier'] == 'critical' && environment.name == 'production'"
  priority = 20

  any_approval {
    min_approvals = 2
  }

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

​

Best Practices

​

Policy Organization

• ✅ Use descriptive policy names
• ✅ Document policy purpose in description
• ✅ Start with permissive policies and tighten over time
• ✅ Test policies in lower environments first
• ✅ Use priority to control evaluation order for overlapping policies

​

Selector Design

• ✅ Be specific with selectors to avoid unexpected matches
• ✅ Use environment selectors for environment-specific rules
• ✅ Use metadata for cross-cutting concerns (team, tier, etc.)
• ✅ Test selector expressions before applying

​

Rule Configuration

• ✅ Set reasonable timeouts and failure limits
• ✅ Use verification to catch issues before they impact users
• ✅ Require approvals for high-risk deployments
• ✅ Use gradual rollouts for large-scale deployments
• ✅ Combine complementary rules (e.g., approval + gradual rollout)

​

Next Steps

• Approval - Require manual sign-off before deployment
• Deployment Dependency - Create service dependencies
• Deployment Window - Control when deployments can occur
• Environment Progression - Enforce deployment order
• Gradual Rollouts - Control deployment pace
• Retry - Configure automatic retry behavior
• Version Cooldown - Batch frequent releases
• Version Selector - Filter deployable versions