cli-jaw 0.1.7 → 0.1.8

package/skills_ref/terraform/module-generation/skills/terraform-stacks/references/deployment-blocks.md

@@ -1,391 +0,0 @@
-# Deployment Configuration Block Reference
-
-Complete reference for all blocks available in Terraform Stack deployment configuration files (`.tfdeploy.hcl`).
-
-## Table of Contents
-
-1. [Identity Token Block](#identity-token-block)
-2. [Locals Block](#locals-block)
-3. [Deployment Block](#deployment-block)
-4. [Deployment Group Block](#deployment-group-block)
-5. [Deployment Auto-Approve Block](#deployment-auto-approve-block)
-
-**Note**: For Publish Output and Upstream Input blocks (linked Stacks), see `linked-stacks.md`.
-
-## Identity Token Block
-
-Generates JWT tokens for OIDC authentication with cloud providers.
-
-### Syntax
-
-```hcl
-identity_token "<token_name>" {
-  audience = [<audience_strings>]
-}
-```
-
-### Arguments
-
-- **token_name** (label, required): Unique identifier for this token
-- **audience** (required): List of audience strings for the JWT
-
-### Accessing Token
-
-Reference the JWT using: `identity_token.<n>.jwt`
-
-### Cloud Provider Audiences
-
-**AWS:**
-```hcl
-identity_token "aws" {
-  audience = ["aws.workload.identity"]
-}
-```
-
-**Azure:**
-```hcl
-identity_token "azure" {
-  audience = ["api://AzureADTokenExchange"]
-}
-```
-
-**Google Cloud:**
-```hcl
-identity_token "gcp" {
-  audience = ["//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>"]
-}
-```
-
-**Setup Documentation:** For detailed instructions on configuring OIDC/workload identity for each cloud provider (including IAM roles, trust policies, and federated credentials), see: https://developer.hashicorp.com/terraform/cloud-docs/dynamic-provider-credentials
-
-### Examples
-
-**Single Token:**
-
-```hcl
-identity_token "aws" {
-  audience = ["aws.workload.identity"]
-}
-
-deployment "production" {
-  inputs = {
-    identity_token = identity_token.aws.jwt
-    role_arn       = var.role_arn
-  }
-}
-```
-
-For complete working examples including multi-region identity token usage, see `examples.md`.
-
-## Locals Block
-
-Defines local values for reuse within deployment configuration.
-
-### Syntax
-
-```hcl
-locals {
-  <n> = <expression>
-}
-```
-
-### Example
-
-```hcl
-locals {
-  aws_regions = ["us-west-1", "us-east-1", "eu-west-1"]
-  role_arn    = "arn:aws:iam::123456789012:role/hcp-terraform-stacks"
-
-  common_inputs = {
-    project_name = "my-app"
-    environment  = "production"
-  }
-}
-```
-
-## Deployment Block
-
-Defines deployment instances of the Stack.
-
-### Syntax
-
-```hcl
-deployment "<deployment_name>" {
-  inputs = {
-    <input_name> = <value>
-  }
-}
-```
-
-### Arguments
-
-- **deployment_name** (label, required): Unique identifier for this deployment
-- **inputs** (required): Map of input variable values
-- **destroy** (optional, default: false): Boolean flag to destroy this deployment
-
-### Constraints
-
-- Minimum 1 deployment per Stack
-- Maximum 20 deployments per Stack
-- No meta-arguments supported (no `for_each`, `count`)
-
-### Destroying a Deployment
-
-To safely remove a deployment from your Stack:
-
-1. Set `destroy = true` in the deployment block
-2. Apply the plan through HCP Terraform
-3. After successful destruction, remove the deployment block from your configuration
-
-**Important**: Using the `destroy` argument ensures your configuration has the provider authentication necessary to properly destroy the deployment's resources.
-
-**Example:**
-```hcl
-deployment "old_environment" {
-  inputs = {
-    aws_region     = "us-west-1"
-    instance_count = 2
-    role_arn       = local.role_arn
-    identity_token = identity_token.aws.jwt
-  }
-  destroy = true  # Mark for destruction
-}
-```
-
-After applying this plan and the deployment is destroyed, remove the entire `deployment "old_environment"` block from your configuration.
-
-### Examples
-
-**Single Deployment:**
-
-```hcl
-deployment "production" {
-  inputs = {
-    aws_region     = "us-west-1"
-    instance_count = 5
-    instance_type  = "t3.large"
-    role_arn       = local.role_arn
-    identity_token = identity_token.aws.jwt
-  }
-}
-```
-
-**Using Locals for Multiple Deployments:**
-
-```hcl
-locals {
-  common_inputs = {
-    role_arn       = "arn:aws:iam::123456789012:role/terraform"
-    identity_token = identity_token.aws.jwt
-    project_name   = "my-app"
-  }
-}
-
-deployment "dev" {
-  inputs = merge(local.common_inputs, {
-    aws_region     = "us-east-1"
-    instance_count = 1
-    environment    = "dev"
-  })
-}
-
-deployment "prod" {
-  inputs = merge(local.common_inputs, {
-    aws_region     = "us-west-1"
-    instance_count = 5
-    environment    = "prod"
-  })
-}
-```
-
-For complete multi-environment and multi-region deployment examples, see `examples.md`.
-
-## Deployment Group Block
-
-Groups deployments together to configure shared settings and auto-approval rules (HCP Terraform Premium tier feature).
-
-### Syntax
-
-```hcl
-deployment_group "<group_name>" {
-  deployments = [<deployment_references>]
-}
-```
-
-### Arguments
-
-- **group_name** (label, required): Unique identifier for this deployment group
-- **deployments** (required): List of deployment references to include in this group
-
-### Purpose
-
-Deployment groups allow you to:
-- Organize deployments logically (by environment, team, region, etc.)
-- Configure shared auto-approval rules for multiple deployments
-- Manage deployments more effectively at scale
-- Establish consistent configuration patterns across all Stacks
-
-### Examples
-
-**Single Deployment Group (Best Practice):**
-
-```hcl
-deployment "production" {
-  inputs = {
-    aws_region     = "us-west-1"
-    instance_count = 5
-    role_arn       = local.role_arn
-    identity_token = identity_token.aws.jwt
-  }
-}
-
-deployment_group "production" {
-  deployments = [deployment.production]
-}
-```
-
-**Multiple Deployment Groups:**
-
-```hcl
-deployment_group "non_production" {
-  deployments = [
-    deployment.development,
-    deployment.staging
-  ]
-}
-
-deployment_group "production" {
-  deployments = [
-    deployment.prod_us_east,
-    deployment.prod_us_west,
-    deployment.prod_eu_west
-  ]
-}
-```
-
-## Deployment Auto-Approve Block
-
-Defines rules that automatically approve deployment plans based on specific conditions (HCP Terraform Premium feature).
-
-### Syntax
-
-```hcl
-deployment_auto_approve "<rule_name>" {
-  deployment_group = deployment_group.<group_name>
-  
-  check {
-    condition = <boolean_expression>
-    reason    = "<failure_message>"
-  }
-}
-```
-
-### Arguments
-
-- **rule_name** (label, required): Unique identifier for this auto-approve rule
-- **deployment_group** (required): Reference to the deployment group this rule applies to
-- **check** (required, one or more): Condition that must be met for auto-approval
-
-### Context Variables
-
-Access plan information through `context` object:
-
-- `context.plan.applyable` - Boolean: plan succeeded without errors
-- `context.plan.changes.add` - Number: resources to add
-- `context.plan.changes.change` - Number: resources to change
-- `context.plan.changes.remove` - Number: resources to remove
-- `context.plan.changes.import` - Number: resources to import
-
-### Important Notes
-
-- All checks must pass for auto-approval to occur
-- If any check fails, manual approval is required
-- HCP Terraform displays the failure reason from failed checks
-- Auto-approve rules only apply to deployments in the specified deployment group
-
-### Examples
-
-**Auto-approve Successful Plans:**
-
-```hcl
-deployment_group "canary" {
-  deployments = [
-    deployment.dev,
-    deployment.staging
-  ]
-}
-
-deployment_auto_approve "applyable_plans" {
-  deployment_group = deployment_group.canary
-  
-  check {
-    condition = context.plan.applyable
-    reason    = "Plan must be applyable without errors"
-  }
-}
-```
-
-**Auto-approve Non-Destructive Changes:**
-
-```hcl
-deployment_group "production" {
-  deployments = [
-    deployment.prod_primary,
-    deployment.prod_secondary
-  ]
-}
-
-deployment_auto_approve "safe_production_changes" {
-  deployment_group = deployment_group.production
-  
-  check {
-    condition = context.plan.changes.remove == 0
-    reason    = "Production deletions require manual approval"
-  }
-  
-  check {
-    condition = context.plan.applyable
-    reason    = "Plan must be successful"
-  }
-}
-```
-
-**Graduated Rollout Pattern:**
-
-```hcl
-deployment_group "canary" {
-  deployments = [deployment.canary]
-}
-
-deployment_group "production" {
-  deployments = [
-    deployment.prod_us,
-    deployment.prod_eu,
-    deployment.prod_asia
-  ]
-}
-
-# Canary auto-approves with strict checks
-deployment_auto_approve "canary_strict" {
-  deployment_group = deployment_group.canary
-  
-  check {
-    condition = context.plan.changes.remove == 0
-    reason    = "Canary cannot delete resources"
-  }
-  
-  check {
-    condition = context.plan.changes.change <= 5
-    reason    = "Canary limited to 5 resource changes"
-  }
-  
-  check {
-    condition = context.plan.applyable
-    reason    = "Plan must be applyable"
-  }
-}
-
-# Production requires manual approval after canary validation
-```
-
-For complete deployment configuration examples with all blocks, see `examples.md`.