terraform-aws-cognito-user-pool: Instructions file for Claude Code

Terraform AWS Cognito User Pool Module - Development Guidelines

Overview

This document outlines Terraform-specific development guidelines for the terraform-aws-cognito-user-pool module, focusing on best practices for AWS Cognito identity and access management infrastructure as code.

Module Structure & Organization

File Organization

• main.tf - Primary Cognito User Pool resource definitions and locals
• variables.tf - Input variable definitions with validation
• outputs.tf - Output value definitions
• versions.tf - Provider version constraints
• client.tf - Cognito User Pool client configurations
• domain.tf - User pool domain configurations
• identity-provider.tf - Identity provider configurations
• managed-login-branding.tf - Managed login branding configurations
• resource-server.tf - Resource server configurations
• ui-customization.tf - UI customization configurations
• user-group.tf - User group configurations

Code Organization Principles

• Group related resources logically in separate files
• Use descriptive locals for complex expressions
• Maintain backward compatibility with existing variable names
• Keep validation logic close to variable definitions

Terraform Best Practices

Resource Creation Patterns

Favor for_each over count for resource creation:

# Preferred: Using for_each
resource "aws_cognito_user_pool_client" "this" {
  for_each = var.enabled ? var.clients : {}

  name         = each.value.name
  user_pool_id = aws_cognito_user_pool.pool[0].id
  # ...
}

# Avoid: Using count when for_each is more appropriate
resource "aws_cognito_user_pool_client" "this" {
  count = var.enabled ? length(var.clients) : 0
  # ...
}

Variables & Validation

Use validation blocks for critical inputs where appropriate:

# Example: Basic validation for naming conventions
variable "user_pool_name" {
  description = "Name of the Cognito User Pool to create"
  type        = string
  default     = null

  validation {
    condition     = var.user_pool_name == null ? true : can(regex("^[0-9A-Za-z-_\\s]{1,128}$", var.user_pool_name))
    error_message = "The user_pool_name must be between 1 and 128 characters, contain only alphanumeric characters, spaces, hyphens, and underscores."
  }
}