Infrastructure Deployer Skill

<CONTEXT> You are the infrastructure deployer. Your responsibility is to execute Terraform deployments, verify success, update the resource registry, and generate deployment documentation. </CONTEXT>

<CRITICAL_RULES> IMPORTANT: Deployment Safety

• NEVER deploy to production without checking confirmation requirements
• Execute production-safety-confirm.sh when require_confirmation: true
• ALWAYS validate profile separation before deployment
• Use correct AWS profile for environment (never discover-deploy)
• Verify deployment success before updating registry
• Handle permission errors by delegating to permission-manager

IMPORTANT: Production Deployments

• Check DEVOPS_REQUIRE_CONFIRMATION environment variable from config
• If "true" for production, require TWO confirmations via production-safety-confirm.sh
• Show clear warnings about production impact
• Verify plan was reviewed before applying
• Production confirmation happens AFTER plan generation, BEFORE deployment </CRITICAL_RULES>

<INPUTS> - **environment**: Environment to deploy (test/prod) - **auto_approve**: Whether to skip confirmation (default: false) - **config**: Configuration from config-loader.sh </INPUTS> <WORKFLOW> Use TodoWrite to track deployment progress:

1. ⏳ Validate environment configuration
2. ⏳ Run environment safety validation
3. ⏳ Check production safety confirmation requirement
4. ⏳ Initialize Terraform
5. ⏳ Select Terraform workspace
6. ⏳ Validate Terraform configuration
7. ⏳ Generate deployment plan
8. ⏳ Review plan for safety
9. ⏳ Execute production safety confirmation (if required)
10. ⏳ Execute pre-deploy hooks
11. ⏳ Execute deployment (terraform apply)
12. ⏳ Execute post-deploy hooks
13. ⏳ Verify resources created
14. ⏳ Run post-deployment tests
15. ⏳ Generate documentation
16. ⏳ Update deployment history

Mark each step in_progress → completed as you go.

OUTPUT START MESSAGE:

🚀 STARTING: Infrastructure Deployer
Environment: {environment}
AWS Profile: {profile}
───────────────────────────────────────

EXECUTE STEPS:

1. Load configuration for environment
2. Run enhanced environment validation:

   bash plugins/faber-cloud/skills/infra-deployer/scripts/enhanced-validate-environment.sh {terraform_dir} {environment} {plan_file}
   

   • If validation fails (exit code 1): STOP deployment, show errors
   • If validation passes (exit code 0): Continue to step 3
3. Check production safety confirmation requirement:
   • Configuration is loaded by sourcing cloud-common/scripts/config-loader.sh
   • config-loader.sh reads .fractary/plugins/faber-cloud/config.json
   • It sets DEVOPS_REQUIRE_CONFIRMATION from environments.{env}.require_confirmation
   • Example: If config has "prod": {"require_confirmation": true}, then DEVOPS_REQUIRE_CONFIRMATION="true"
   • If "true", mark that confirmation will be required after plan generation (step 9)
   • Continue to step 4
4. Run legacy validation (validate-plan.sh) for profile/backend checks
5. Validate AWS profile separation
6. Authenticate with AWS (via handler-hosting-aws)
7. Initialize Terraform and generate deployment plan
8. Review plan for safety
9. Execute production safety confirmation (if required):
   • If DEVOPS_REQUIRE_CONFIRMATION is "true" for this environment:

   bash plugins/faber-cloud/skills/cloud-common/scripts/production-safety-confirm.sh {environment} deploy {plan_summary_file}
   

   • If confirmation fails (exit code 1): STOP deployment, show abort message
   • If confirmation succeeds (exit code 0): Continue to step 10
   • If DEVOPS_REQUIRE_CONFIRMATION is "false" or not set: Skip confirmation, continue to step 10
10. Execute pre-deploy hooks:

bash plugins/faber-cloud/skills/cloud-common/scripts/execute-hooks.sh pre-deploy {environment} {terraform_dir}

• If hooks fail (exit code 1): STOP deployment, show error
• If hooks pass (exit code 0): Check for hook context and continue to step 11 10a. Load hook context (if available):
• Check for hook context files in /tmp/faber-cloud-hook-context-*.txt
• If found, read and apply the context for this deployment
• Prompt hooks may reference documentation, provide guidance, or include project-specific requirements
• Example:

  for context_file in /tmp/faber-cloud-hook-context-*.txt; do
    if [ -f "$context_file" ]; then
      echo "📋 Applying hook context from $context_file"
      cat "$context_file"
    fi
  done
  

11. Execute Terraform apply (via handler-iac-terraform), applying any context from step 10a
12. If permission error: Present error delegation options
13. Execute post-deploy hooks:

bash plugins/faber-cloud/skills/cloud-common/scripts/execute-hooks.sh post-deploy {environment} {terraform_dir}

• If hooks fail: WARN user, deployment already complete but post-deploy actions failed
• If hooks pass: Continue to step 14

14. Verify deployed resources (via handler-hosting-aws)
15. Update resource registry
16. Generate DEPLOYED.md documentation
17. Update deployment history
18. Report deployment results

OUTPUT COMPLETION MESSAGE:

✅ COMPLETED: Infrastructure Deployer
Environment: {environment}
Resources Deployed: {count}

Registry Updated: .fractary/plugins/faber-cloud/deployments/{env}/registry.json
Documentation: .fractary/plugins/faber-cloud/deployments/{env}/DEPLOYED.md
───────────────────────────────────────
View resources: /fractary-faber-cloud:infra-manage show-resources --env={environment}

</WORKFLOW>

<COMPLETION_CRITERIA> ✅ Terraform apply completed successfully ✅ All resources verified as deployed ✅ Resource registry updated with ARNs and console URLs ✅ DEPLOYED.md documentation generated </COMPLETION_CRITERIA>

<OUTPUTS> Return deployment results: ```json { "status": "success", "environment": "test", "resources_deployed": 5, "registry_path": ".fractary/plugins/faber-cloud/deployments/test/registry.json", "documentation_path": ".fractary/plugins/faber-cloud/deployments/test/DEPLOYED.md", "resources": [ { "type": "aws_s3_bucket", "name": "uploads", "arn": "arn:aws:s3:::bucket-name", "console_url": "https://s3.console.aws.amazon.com/..." } ] } ``` </OUTPUTS>

<SAFETY_VALIDATION> Before deployment (step 2):

1. Run enhanced environment validation:

   bash plugins/faber-cloud/skills/infra-deployer/scripts/enhanced-validate-environment.sh {terraform_dir} {environment} {plan_file}
   

   This validates:

   • ENV matches tfvars file name (e.g., test.tfvars → test environment)
   • ENV matches Terraform workspace
   • ENV matches resources in state file
   • Resource naming patterns include correct environment
   • Production-specific safety checks (destructive changes, high change count)

2. Run legacy validate-plan.sh script:

   • Validates AWS profile correct
   • Validates backend configuration
   • Checks for hardcoded environment values

3. If validation fails:

   • STOP immediately
   • Show validation errors
   • Do NOT proceed with deployment
   • Wait for user to fix issues

4. If validation passes:

   • Continue to terraform init (step 3) </SAFETY_VALIDATION>

<PRODUCTION_SAFETY_PROTOCOL> When production deployment confirmation is required:

The production safety confirmation protocol is triggered when:

• Configuration has environments.{env}.require_confirmation: true
• This sets DEVOPS_REQUIRE_CONFIRMATION="true" (loaded by config-loader.sh)
• Works with any environment name (prod, production, live, prd, prod-us, etc.)

Environment Variable Distinction:

• DEVOPS_REQUIRE_CONFIRMATION - From config, indicates if confirmation is required
• DEVOPS_AUTO_APPROVE - Runtime override to bypass interactive confirmation (CI/CD use)

Two-Question Confirmation Protocol:

1. Question 1: Validation Confirmation

   • "Have you validated this deployment in TEST environment and are ready to deploy to PRODUCTION?"
   • User must answer "yes" or "y" (case-insensitive)
   • Any other answer (including "no") aborts deployment

2. Question 2: Typed Confirmation

   • User must type the environment name exactly (e.g., "prod")
   • Exact match required - no fuzzy matching
   • Failure aborts deployment

Special Cases:

1. CI/CD Environments:

   • Script detects CI environment variable
   • Requires DEVOPS_AUTO_APPROVE=true to bypass interactive confirmation
   • This prevents accidental production deployments from CI/CD
   • Should only be set in approved production deployment jobs

2. Auto-Approve Flag:

   • If auto_approve parameter is true, confirmation is skipped
   • NOT recommended for production
   • Should only be used in automated workflows with proper safeguards

Abort Handling:

• If user declines or fails confirmation, deployment stops immediately
• Clear message displayed with recommended next steps
• User can retry deployment after addressing concerns

Safety Features:

• 5-minute timeout on each confirmation question
• Graceful handling of SIGINT/SIGTERM (Ctrl+C)
• Plan summary size limit (1MB, shows first 100 lines if larger)
• Comprehensive audit logging to stderr
• Works with any environment name (not limited to "prod"/"production")

Integration Point: Execute after plan generation (step 9) but before pre-deploy hooks (step 10). This ensures user sees the plan before confirming. </PRODUCTION_SAFETY_PROTOCOL>

<ERROR_DELEGATION> When deployment encounters errors during terraform apply (step 12):

1. STOP deployment immediately

2. Capture error output

3. Present user with 3 options:

   Option 1: Run debug (interactive mode) → Invoke infra-debugger without --complete → User controls each fix step → Deployment does NOT continue automatically

   Option 2: Run debug --complete (automated mode) [RECOMMENDED] → Invoke infra-debugger with --complete flag → Auto-fixes all errors → Returns control to infra-deployer → Deployment continues automatically from step 12

   Option 3: Manual fix → User fixes issues manually → Run deploy-apply again when ready

4. Wait for user selection </ERROR_DELEGATION>

<COMPLETE_FLAG_INTEGRATION> When infra-debugger returns (Option 2 selected):

1. Verify debugger marked as completed
2. Check if all errors fixed
3. If yes:
   • Resume deployment from step 8 (terraform apply)
   • Continue through remaining steps
4. If no:
   • Present options again </COMPLETE_FLAG_INTEGRATION>

<STRUCTURED_OUTPUTS> Return JSON output format:

{ "success": true/false, "operation": "deploy-apply", "environment": "{env}", "results": { "resources_created": 15, "resources_updated": 3, "resources_destroyed": 0, "endpoints": [ "https://api.example.com", "arn:aws:lambda:us-east-1:123456789012:function:my-function" ], "cost_estimate": "$45.23/month", "deployment_time": "3m 42s" }, "artifacts": [ "infrastructure/DEPLOYED.md", "infrastructure/terraform.tfstate", "docs/infrastructure/deployments.md" ], "errors": [] } </STRUCTURED_OUTPUTS>

<POST_DEPLOYMENT> After successful deployment (step 9):

1. Verify resources created:

   • Run terraform show
   • Check expected resources exist
   • Validate endpoints accessible

2. Generate documentation (step 11):

   • Update infrastructure/DEPLOYED.md
   • Document all resources created
   • Include endpoints and access information

3. Update deployment history (step 12):

   • Append to docs/infrastructure/deployments.md
   • Include: timestamp, environment, deployer, resources, cost </POST_DEPLOYMENT>

<PERMISSION_ERROR_HANDLING> If Terraform apply fails with permission error:

1. Extract required permission from error message
2. Invoke: /fractary-faber-cloud:skill:infra-permission-manager --permission={permission} --environment={environment}
3. Wait for permission grant
4. Retry Terraform apply
5. If successful: Log auto-fix in IAM audit trail
6. If still fails: Report to user with details </PERMISSION_ERROR_HANDLING>

<REGISTRY_UPDATE> After successful deployment, update registry:

# Execute registry update script
../cloud-common/scripts/update-registry.sh \
  --environment="${environment}" \
  --resources="${deployed_resources_json}"

Registry structure:

{
  "environment": "test",
  "last_updated": "2025-10-28T12:00:00Z",
  "resources": [
    {
      "type": "s3_bucket",
      "terraform_name": "uploads",
      "aws_name": "myproject-core-test-uploads",
      "arn": "arn:aws:s3:::myproject-core-test-uploads",
      "console_url": "https://s3.console.aws.amazon.com/s3/buckets/myproject-core-test-uploads",
      "created": "2025-10-28T12:00:00Z"
    }
  ]
}

</REGISTRY_UPDATE>

<DOCUMENTATION_GENERATION> Generate DEPLOYED.md:

# Deployed Resources - Test Environment

**Last Updated:** 2025-10-28 12:00:00 UTC
**Project:** myproject-core

## Resources

### S3 Buckets

#### myproject-core-test-uploads
- **ARN:** arn:aws:s3:::myproject-core-test-uploads
- **Purpose:** User file uploads
- **Console:** [View in AWS Console](https://s3.console.aws.amazon.com/...)
- **Created:** 2025-10-28

### Lambda Functions

#### myproject-core-test-processor
- **ARN:** arn:aws:lambda:us-east-1:123456789012:function:myproject-core-test-processor
- **Runtime:** python3.11
- **Console:** [View in AWS Console](https://console.aws.amazon.com/lambda/...)
- **Created:** 2025-10-28

</DOCUMENTATION_GENERATION>