Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (58 loc) · 3.83 KB

AGENTS.md

File metadata and controls

72 lines (58 loc) · 3.83 KB

AGENTS.md — terraform-aws-lambda

Project overview

Terraform module for AWS Lambda with opinionated defaults for IAM, logging, VPC, event sources, and deployments. Published to the Terraform Registry.

Key files

  • main.tf — Two aws_lambda_function resources (normal + external lifecycle for CodeDeploy/CLI updates), selected via var.ignore_external_function_updates
  • iam.tf — IAM role, conditional policy attachments (VPC, tracing, Lambda Insights, SSM, CloudWatch Logs)
  • variables.tf — REQUIRED section first, then OPTIONAL with section comments
  • outputs.tf — Core outputs (arn, function_name, role_name, role_arn, invoke_arn, version, log group, log group arn)
  • cloudwatch_logs.tf, cloudwatch_event_rules.tf, event_source_mappings.tf, sns_subscriptions.tf — Feature-specific resources
  • modules/deployment/ — CodePipeline/CodeDeploy submodule

Conventions

Terraform style

  • terraform fmt enforced via pre-commit
  • Alphabetical attribute ordering within resources
  • Dynamic blocks: for_each = var.x == null ? [] : [var.x]
  • Count-based conditional resources: count = var.feature_enabled ? 1 : 0
  • Locals for computed values (function ARN, role name with 64-char limit, log group name)
  • Each feature area has its own .tf file with local variables as needed

Variables

  • snake_case naming
  • Detailed descriptions in imperative style ("A unique name...", "Enables your Lambda function to...")
  • null default for optional object variables
  • Types always explicit

Naming

  • IAM role: ${function_name}-${region} (truncated to 64 chars)
  • Log group: /aws/lambda/${function_name}
  • Resource name prefixes: ${var.function_name}-<feature>

Commit messages

Conventional commits enforced by CI: feat:, fix:, chore:, refactor:, docs:, ci:

  • Lowercase subject, no period at end
  • Semantic PR titles required

Versioning

  • Semantic versioning via git tags (e.g. v8.6.0)
  • make release BUMP=minor to bump, tag, and create GitHub release

Examples

All in examples/. Each uses module "fixtures" from examples/fixtures/ for shared test data (lambda.zip, random function name). Examples serve as integration tests — run terraform apply to verify.

Runtime-specific examples (examples/runtimes/) use Makefiles with standardized targets (help, package, tf, clean). Build logic stays in the Makefile, infrastructure in Terraform.

CI/CD

  • pre-commit: terraform_fmt, terraform_validate, terraform_tflint, terraform_trivy, terraform_docs
  • GitHub Actions: static-checks (pre-commit matrix with min+max TF versions), pr-title (semantic), stale
  • terraform_docs: auto-generates README.md input/output tables from variables.tf/outputs.tf
  • trivy: blocks HIGH/CRITICAL findings; use #trivy:ignore:AVD-xxx with justification comment
  • tflint: AWS plugin enabled; invalid_handler and invalid_runtime rules disabled

Adding features

  1. Add variable to variables.tf (in alphabetical order within the OPTIONAL section)
  2. Add dynamic block to BOTH aws_lambda_function resources in main.tf
  3. Add IAM permissions to iam.tf if the feature needs them (conditional on the variable)
  4. Add/update an example in examples/
  5. Run pre-commit run -a to update README.md and validate
  6. Run terraform apply in the example directory to verify

Important: do NOT

  • Edit text between <!-- BEGIN_TF_DOCS --> and <!-- END_TF_DOCS --> in README.md — it is auto-generated by terraform_docs
  • Run terraform apply in CI — examples are tested manually
  • Skip pre-commit hooks (--no-verify) — fix the underlying issue instead
  • Use filebase64sha256() for deployment zips without a fileexists() guard — CI runs validate without build artifacts

Provider requirements

  • Terraform >= 1.5.7
  • AWS provider >= 6.0