docs

docs/census-examples.md

@@ -0,0 +1,275 @@
+# Census Bureau Usage Examples
+
+This guide provides real-world examples of using the Terraform Upgrade Tool specifically for Census Bureau Terraform configurations. These examples cover common patterns and scenarios encountered in Census environments.
+
+## Table of Contents
+
+- [Module Migration Best Practices](#module-migration-best-practices)
+- [Census Module Upgrade Matrix](#census-module-upgrade-matrix)
+- [EDL-Specific Upgrade Patterns](#edl-specific-upgrade-patterns)
+- [Census Security Implementation Patterns](#census-security-implementation-patterns)
+- [Census AWS Account Structure Handling](#census-aws-account-structure-handling)
+- [Advanced Census Configuration Patterns](#advanced-census-configuration-patterns)
+- [Best Practices for Census-Specific Terraform Upgrades](#best-practices-for-census-specific-terraform-upgrades)
+- [Resources](#resources)
+
+## Module Migration Best Practices
+
+This section provides guidance on upgrading commonly used Census Bureau modules.
+
+### Census Module Upgrade Matrix
+
+| Module | Original Version | Recommended Version | Notes |
+|--------|------------------|---------------------|-------|
+| terraform-aws-vpc-setup | v1.x | ref=tf-upgrade | Regional subnet changes |
+| terraform-aws-s3 | v0.9.x | v1.0.0+ | New encryption settings |
+| terraform-aws-iam-role | v0.5.x | v1.0.0+ | Permission boundaries |
+| terraform-aws-edl-launch-instance | v0.8.x | ref=tf-upgrade | Updated AMI handling |
+| terraform-aws-common-security-groups | v0.4.x | v1.0.0+ | New rule structures |
+| terraform-aws-tls-certificate | v0.3.x | v1.0.0+ | Updated validation method |
+
+## EDL-Specific Upgrade Patterns
+
+### EDL Data Workflow Upgrade
+
+EDL data workflow configurations often have special patterns. Here's an example of upgrading an EDL data pipeline:
+
+```bash
+# First, analyze the EDL workflow directory
+make analyze DIR=/path/to/edl-workflow
+
+# Perform a targeted dry-run for EDL patterns
+make dry-run DIR=/path/to/edl-workflow EDL_AWARE=true
+
+# Upgrade with EDL-specific handling
+make upgrade DIR=/path/to/edl-workflow EDL_AWARE=true
+```
+
+The `EDL_AWARE` flag triggers special handling for EDL module sources and tag patterns.
+
+### EDL Module Version Reference Pattern
+
+For EDL modules, follow this version reference pattern after upgrading to Terraform 1.x:
+
+```terraform
+module "edl_processing" {
+  source = "git::https://github.com/census-bureau-internal/terraform-aws-edl-workflow.git?ref=tf-upgrade"
+  
+  // Rest of module configuration
+}
+```
+
+The `tf-upgrade` reference points to the 1.x-compatible branch maintained by the Census EDL team.
+
+## Census Security Implementation Patterns
+
+### VPC Security Group Pattern
+
+Census VPC security group configurations use a specific pattern. Here's an example upgrade:
+
+```terraform
+# Before upgrade (0.12.x)
+resource "aws_security_group" "app_sg" {
+  name        = "${var.environment}-${var.app_name}-sg"
+  description = "Security group for ${var.app_name}"
+  vpc_id      = var.vpc_id
+  
+  tags = {
+    "boc:application" = var.app_name
+    "boc:environment" = var.environment
+    "Name"            = "${var.environment}-${var.app_name}-sg"
+  }
+}
+
+# After upgrade (1.x)
+resource "aws_security_group" "app_sg" {
+  name        = "${var.environment}-${var.app_name}-sg"
+  description = "Security group for ${var.app_name}"
+  vpc_id      = var.vpc_id
+  
+  tags = {
+    "boc:application" = var.app_name
+    "boc:environment" = var.environment
+    "Name"            = "${var.environment}-${var.app_name}-sg"
+  }
+}
+```
+
+Note that the security group resource itself doesn't change significantly, but associated rules and provider declarations would be updated.
+
+### IAM Role Pattern
+
+Census Bureau IAM roles follow a standard pattern. Here's how they're upgraded:
+
+```terraform
+# Before upgrade (0.12.x)
+module "app_role" {
+  source = "git::https://github.com/census-bureau-internal/terraform-aws-iam-role.git?ref=v0.5.0"
+  
+  name               = "${var.environment}-${var.app_name}-role"
+  assume_role_policy = data.aws_iam_policy_document.assume_role.json
+  
+  policy_arns = [
+    "arn:aws-us-gov:iam::aws:policy/AmazonS3ReadOnlyAccess",
+    aws_iam_policy.custom_policy.arn
+  ]
+  
+  tags = var.tags
+}
+
+# After upgrade (1.x)
+module "app_role" {
+  source = "git::https://github.com/census-bureau-internal/terraform-aws-iam-role.git?ref=v1.0.0"
+  
+  name               = "${var.environment}-${var.app_name}-role"
+  assume_role_policy = data.aws_iam_policy_document.assume_role.json
+  
+  policy_arns = [
+    "arn:aws-us-gov:iam::aws:policy/AmazonS3ReadOnlyAccess",
+    aws_iam_policy.custom_policy.arn
+  ]
+  
+  tags = var.tags
+}
+```
+
+The module reference is updated to the 1.x-compatible version.
+
+## Census AWS Account Structure Handling
+
+### Cross-Account Resource Access Pattern
+
+Census Bureau uses a multi-account structure. Here's how to handle cross-account resource references during upgrades:
+
+```terraform
+# Before upgrade (0.12.x)
+data "terraform_remote_state" "network" {
+  backend = "s3"
+  config = {
+    bucket   = "census-tfstate-${var.network_account_id}"
+    key      = "network/terraform.tfstate"
+    region   = "us-gov-west-1"
+    role_arn = "arn:aws-us-gov:iam::${var.network_account_id}:role/TerraformAccessRole"
+  }
+}
+
+# After upgrade (1.x)
+data "terraform_remote_state" "network" {
+  backend = "s3"
+  config = {
+    bucket   = "census-tfstate-${var.network_account_id}"
+    key      = "network/terraform.tfstate"
+    region   = "us-gov-west-1"
+    role_arn = "arn:aws-us-gov:iam::${var.network_account_id}:role/TerraformAccessRole"
+  }
+}
+```
+
+The remote state data source itself doesn't change, but the provider configuration would be updated to use the required_providers block.
+
+### Census AWS Profile Conventions
+
+When using the AWS profile for different Census accounts, follow this pattern:
+
+```bash
+# List the available profiles
+aws configure list-profiles
+
+# Export the profile before running the upgrade tool
+export AWS_PROFILE=123456789012.AdministratorAccess
+
+# Run the upgrade with the profile
+make upgrade DIR=/path/to/terraform/config
+```
+
+The tool will detect Census AWS profile naming conventions (account_id.role_name) and use them appropriately.
+
+## Advanced Census Configuration Patterns
+
+### Dynamic Backend Configuration
+
+Census often uses dynamic backend configurations. These are handled carefully during upgrade:
+
+```terraform
+# Before upgrade (0.12.x)
+terraform {
+  backend "s3" {
+    # These values are populated from environment variables
+  }
+}
+
+# After upgrade (1.x)
+terraform {
+  backend "s3" {
+    # These values are populated from environment variables
+  }
+  
+  required_version = ">= 1.0.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 4.0"
+    }
+  }
+}
+```
+
+The upgrade tool preserves the backend configuration while adding the required version constraints.
+
+### Census Tag Standardization
+
+Census has standard tag conventions that are preserved during upgrade:
+
+```terraform
+# Common pattern for Census tag variables
+variable "tags" {
+  type        = map(string)
+  description = "Standard Census tags"
+  default     = {}
+}
+
+locals {
+  standard_tags = merge(var.tags, {
+    "boc:project"       = var.project_name
+    "boc:cost-center"   = var.cost_center
+    "boc:technical-poc" = var.tech_poc
+    "Name"              = var.name
+  })
+}
+
+# This pattern is preserved during upgrade
+```
+
+## Best Practices for Census-Specific Terraform Upgrades
+
+1. **Upgrade Order**:
+   - Start with foundation modules (vpc, networking)
+   - Move to security modules (iam, security groups)
+   - Then upgrade application infrastructure
+   - Finally, upgrade pipeline and deployment configurations
+
+2. **AWS Profile Management**:
+   - Use a consistent AWS profile naming convention
+   - Maintain role-based profiles for different environments
+   - Test upgraded configurations with appropriate role permissions
+
+3. **Module Version References**:
+   - For Census modules, prefer specific version tags (e.g., `?ref=v1.0.0`)
+   - For modules still in transition, use the `tf-upgrade` branch
+   - After upgrade completion, migrate all references to specific versions
+
+4. **Validation Strategy**:
+   - Use `terraform validate` after each version upgrade step
+   - Compare resource counts with `terraform plan` before applying
+   - Test both successful creation and updates for key resources
+
+5. **Census-Specific Code Patterns**:
+   - Keep `boc:` tag prefixes consistent across resources
+   - Update comments to reflect current Census naming conventions
+   - Maintain standard file organization (variables.tf, outputs.tf, main.tf)
+
+## Resources
+
+- Census Bureau Module Repository: `https://github.com/census-bureau-internal/terraform-modules`
+- Census Terraform Standards: `https://wiki.census.gov/terraform-standards`
+- Terraform Provider Documentation for AWS GovCloud: `https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/custom-service-endpoints#aws-govcloud`