Comprehensive Rules for writing, testing, and operating Infrastructure-as-Code (IaC) with Terraform (HCL) as primary language and guidance for OpenTofu, Pulumi, CloudFormation, Azure Bicep, and Crossplane.
Your infrastructure shouldn't be a source of constant anxiety. Every deployment, every environment change, every compliance audit – they're all opportunities for things to break, drift, or expose security gaps. You know the drill: what works in staging mysteriously fails in production, manual console changes create drift you discover weeks later, and that "quick fix" bypasses your entire review process.
Let's be honest about what actually happens in infrastructure management:
Configuration Drift Crisis: That EC2 instance someone "quickly modified" in the console? It's now completely out of sync with your Terraform state, and you won't discover it until something breaks in production.
Module Chaos: Your team has six different ways to provision a VPC because everyone copy-pastes resource blocks instead of using versioned, reusable modules. Each variation has its own subtle bugs and security gaps.
Security Blind Spots: Hard-coded secrets, public S3 buckets, unencrypted state files – all the things that pass code review because everyone's focused on functionality, not security policy.
Review Bottlenecks: Infrastructure changes sit in PR limbo because reviewing HCL requires deep context that only two people on your team possess. Meanwhile, deployment pressure mounts.
State Management Nightmares: Remote state locks, workspace confusion, and the dreaded "someone else is running terraform apply" error that blocks your entire deployment pipeline.
These Cursor Rules transform your infrastructure development from reactive firefighting into proactive, systematic engineering. Instead of wrestling with tools and processes, you'll have an AI assistant that understands infrastructure patterns, security requirements, and operational best practices across the entire IaC ecosystem.
Here's what changes immediately:
Intelligent Code Generation: Generate complete Terraform modules, Pulumi components, or CloudFormation templates that follow security best practices, include proper error handling, and integrate with your existing patterns.
Automatic Security Integration: Every resource gets proper tagging, encryption settings, and security group configurations. No more "we'll secure it later" technical debt.
Multi-Tool Expertise: Whether you're working in Terraform, Pulumi, CloudFormation, Bicep, or Crossplane, you get consistent, expert-level assistance with tool-specific best practices.
Eliminate Security Review Cycles: Generate infrastructure code that passes security scans on the first try. Built-in OPA policy integration means your code aligns with compliance requirements from day one.
Accelerate Module Development: Create reusable, properly documented modules in minutes instead of hours. Automatic generation of variables.tf, outputs.tf, and comprehensive README documentation.
Streamline Multi-Cloud Workflows: Get consistent patterns whether you're provisioning AWS, Azure, or GCP resources. No more context-switching between different provider conventions.
Reduce State Management Issues: Proper remote state configuration, workspace management, and lock handling patterns are automatically applied to every project.
Before: Spend 3 hours creating a VPC module, then another hour adding security groups, another 30 minutes writing documentation, plus debugging time when security scan fails.
After: Generate a complete, security-compliant VPC module with proper input validation, outputs, and documentation in under 5 minutes. Security scans pass immediately.
# Generated module structure with all best practices
module "vpc" {
source = "internal/network/aws"
version = "~> 2.1"
name = var.environment
cidr = var.cidr_block
# Automatic tagging compliance
tags = merge(var.common_tags, {
Module = "network/vpc"
Owner = var.team_owner
})
# Built-in security defaults
enable_flow_logs = true
flow_logs_s3_bucket = var.audit_bucket
}
Before: Copy-paste Terraform configurations between environments, manually adjust variables, hope you didn't miss any environment-specific differences.
After: Generate workspace-aware configurations with proper variable management and environment-specific validation rules.
# Environment-aware validation
variable "instance_type" {
type = string
validation {
condition = terraform.workspace == "prod" ?
contains(["m5.large", "m5.xlarge"], var.instance_type) : true
error_message = "Production requires m5.large or larger instances."
}
}
Before: Write infrastructure code, submit PR, fail security scan, fix issues, repeat until it passes.
After: Generate code that includes security best practices by default – encryption, proper IAM roles, network security, and compliance tagging.
# Automatic security baseline
resource "aws_s3_bucket" "data" {
bucket = local.bucket_name
# Security defaults included
server_side_encryption_configuration {
rule {
apply_server_side_encryption_by_default {
sse_algorithm = "AES256"
}
}
}
# Automatic policy integration
lifecycle {
prevent_destroy = var.environment == "prod"
}
}
Generate Complete Modules:
Create a Terraform module for an AWS ALB with security best practices, proper tagging, and CloudWatch integration
Multi-Tool Translation:
Convert this Terraform configuration to Pulumi TypeScript while maintaining the same security posture
Security-First Development:
Review this infrastructure code for security vulnerabilities and suggest improvements following AWS security best practices
Documentation Automation:
Generate comprehensive documentation for this Terraform module including examples, inputs, outputs, and architecture diagrams
75% Reduction in Security Review Cycles: Code generated with security best practices passes initial security scans, eliminating multiple review rounds.
60% Faster Module Development: Complete, documented, reusable modules generated in minutes instead of hours of manual coding.
50% Fewer Production Issues: Proper validation, error handling, and operational patterns reduce deployment failures and post-deployment fixes.
Eliminate Configuration Drift: Built-in drift detection patterns and proper state management prevent manual changes from breaking your infrastructure.
Standardize Team Practices: Consistent code patterns across all team members, regardless of their IaC experience level.
You'll immediately notice the difference in your code reviews – instead of debating implementation details, you're focusing on business logic and architectural decisions. Your infrastructure becomes more reliable, more secure, and significantly easier to maintain.
The rules work across your entire infrastructure stack, from Terraform and Pulumi to CloudFormation and Kubernetes operators. One consistent approach, multiple tool expertise, zero context switching.
Your infrastructure development workflow transforms from reactive problem-solving to proactive system design. You're not just writing code – you're building reliable, secure, scalable infrastructure systems that your entire team can confidently maintain and extend.
You are an expert in Infrastructure-as-Code across Terraform, OpenTofu, Pulumi (TypeScript/Python/Go), AWS CloudFormation, Azure Bicep, and Kubernetes-native Crossplane.
Key Principles
- Declarative First: describe desired state, let the engine converge; avoid imperative scripts unless unavoidable (e.g., data migrations).
- Version-Control Everything: every *.tf, *.bicep, *.yaml, *.ts file lives in Git; no manual console changes.
- Modular, Reusable, Versioned: publish Terraform modules/ Pulumi packages with semantic version tags; no copy-paste resources.
- Idempotency & Convergence: code can be applied repeatedly with no unintended diffs.
- Policy-as-Code: security, compliance, cost rules written in OPA/Conftest or Terraform Cloud Sentinel.
- GitOps Workflow: PR-based changes, mandatory review + automated checks before merge.
- Secrets Never in Code: reference secrets from Vault, AWS Secrets Manager, Azure Key Vault, or SSM; inject at runtime.
- Document Everything: README per module with inputs/outputs, architecture diagram, example usage.
- Continuous Drift Detection: schedule terraform plan –detailed-exitcode and Crossplane drift-alert; alert on divergence.
HCL / Terraform / OpenTofu
- File Naming: one resource type per file; 00_providers.tf, 10_data.tf, 20_resources_<module>.tf, 90_outputs.tf.
- Block Ordering: provider → data → resource → locals → modules → outputs.
- Use snake_case for variables, locals, outputs; avoid camelCase.
- Always pin provider & module versions (>= x.y.z, < x.y+1.0).
- Enable TF linting (tflint, tfsec, terraform-fmt) in pre-commit.
- Local values for computed expressions; never embed complex logic in resource arguments.
- Use for_each over count to avoid index drift.
- Separate remote state backend (S3/GCS/Azure Blob) with state lock (DynamoDB/Cloud Storage Locks).
- Prefer workspace-per-environment pattern (prod, stage) over separate repos.
- Example:
```hcl
module "vpc" {
source = "appcorp/network/aws" # versioned in registry
version = "~> 3.2"
name = var.env
cidr = var.cidr_block
}
```
Pulumi (TypeScript)
- Use config.<stack>.yaml for per-env settings; keep defaults in code.
- Use `StackReference` for cross-stack outputs instead of environment variables.
- Wrap resource creation in component resources for reuse.
- Example:
```ts
import * as aws from "@pulumi/aws";
export class VpcModule extends pulumi.ComponentResource {
public readonly vpcId: pulumi.Output<string>;
constructor(name: string, args: VpcArgs, opts?: pulumi.ComponentResourceOptions) {
super("custom:network:VpcModule", name, {}, opts);
const vpc = new aws.ec2.Vpc(name, { cidrBlock: args.cidr });
this.vpcId = vpc.id;
}
}
```
AWS CloudFormation / CDK
- Prefer YAML templates.
- Use nested stacks for >200 resources.
- Tag all resources with CostCenter, Owner, Env.
Azure Bicep
- One module per resource group; use `@description` on all params.
- Enforce `targetScope="subscription"` for shared infra.
Crossplane
- Define `Composition` + `CompositeResourceDefinition` to abstract provider details.
- Use `kubectl-schemahero` to validate CRDs before apply.
Error Handling and Validation
- Run `terraform validate`, `terraform plan -detailed-exitcode`, `tflint`, `tfsec`, `checkov` in CI.
- Fail pipeline on spectral severity ≥ medium.
- Early exit pattern: stop plan/apply if required variable missing or feature flag disabled via `terraform.workspace`.
- Use `lifecycle { prevent_destroy = true }` on critical resources; create override map for exceptions.
Framework-Specific Rules
Terraform/OpenTofu
- State encryption must be enabled (`encrypt = true`) in backend.
- Use `precondition`/`postcondition` blocks (0.13+) for invariants.
- Implement `partial_configuration` for S3 remote endpoints in CI; never store credentials in code.
Pulumi
- Wrap errors with context: `throw new pulumi.ResourceError("msg", this)`.
- Use `pulumi.all` to aggregate Outputs; avoid `apply` chains longer than 3 levels (unreadable).
CloudFormation
- Use Change Sets for manual approval deployment stages.
- Configure Stack Policy to BLOCK delete of prod resources.
Additional Sections
Testing & CI/CD
- Pre-commit: terraform fmt ‑recursive, tflint, tfsec, checkov.
- PR pipeline: terraform init ‑backend-config="…", terraform validate, terraform plan (upload as artifact), OPA policy test.
- Post-merge: automatically apply to non-prod; gated manual approval for prod.
Security & Compliance
- OPA/Rego rules for: no public S3 buckets, mandatory tagging, AMD encryption.
- Rotate state-backend access keys every 90 days; enforce via CI check.
- Enable AWS IAM access analyzer to detect cross-account roles.
Performance & Cost Optimization
- Use `aws_ec2_autoscaling_group` with predictive scaling; minimize idle capacity.
- Run `terraform cost-estimate` to comment projected delta on PR.
Documentation & Collaboration
- Auto-generate Markdown docs from Terraform variables + outputs via terraform-docs in pre-commit.
- Architecture diagrams via `terraform graph | dot -Tsvg` committed in /docs.
- PR template checklist: plan attached, security scan pass, policy pass, reviewer sign-off.
Directory Layout Example
```
infra/
├── modules/
│ └── vpc/
│ ├── main.tf
│ ├── variables.tf
│ ├── outputs.tf
│ └── README.md
├── envs/
│ ├── prod/
│ │ └── main.tfvars
│ └── stage/
│ └── main.tfvars
├── policies/
│ └── deny_public_s3.rego
├── .tflint.hcl
└── .pre-commit-config.yaml
```
Common Pitfalls & How to Avoid
- Drift due to console edits → enable CloudTrail/Activity Logs and `terraform plan` nightly.
- State lock contention → detect via 423 exit; back-off with exponential retry.
- Over-use of `count` → switching order destroys/creates; migrate to `for_each` using map keys.