Day 7 - Improve the Terraform Module

Solution

Enhanced Documentation

README.md

# AWS S3 Bucket Terraform Module

Production-ready Terraform module for creating AWS S3 buckets with security best practices.

## Features

- 🔒 **Security First**: Public access blocked by default
- 🔄 **Versioning**: Optional versioning support
- 🔐 **Encryption**: AES256 or KMS encryption
- 📋 **Lifecycle Rules**: Automated object management
- 🏷️ **Tagging**: Consistent resource tagging
- ✅ **Validated**: Automated testing and validation

## Usage

### Basic Example

```hcl
module "bucket" {
  source = "git::https://github.com/yourorg/terraform-aws-s3-bucket.git?ref=v1.0.0"

  bucket_name = "my-application-data"
  environment = "production"

  tags = {
    Project = "MyApp"
  }
}

With Lifecycle Rules

module "bucket_with_lifecycle" {
  source = "git::https://github.com/yourorg/terraform-aws-s3-bucket.git?ref=v1.0.0"

  bucket_name = "my-app-logs"
  environment = "production"

  lifecycle_rules = [
    {
      id              = "archive-logs"
      enabled         = true
      transition_days = 30
      storage_class   = "GLACIER"
      expiration_days = 365
    }
  ]
}

Requirements

Name	Version
terraform	>= 1.5
aws	~> 5.0

Providers

Name	Version
aws	~> 5.0

Inputs

Name	Description	Type	Default	Required
bucket_name	Name of the S3 bucket	string	n/a	yes
environment	Environment name	string	"dev"	no
versioning_enabled	Enable versioning	bool	true	no
block_public_access	Block all public access	bool	true	no
kms_key_id	KMS key for encryption	string	null	no
lifecycle_rules	Lifecycle management rules	list(object)	null	no
tags	Additional resource tags	map(string)	{}	no

Outputs

Name	Description
bucket_id	The name of the bucket
bucket_arn	The ARN of the bucket
bucket_domain_name	The domain name of the bucket
bucket_regional_domain_name	The regional domain name
bucket_region	The AWS region

Examples

• Basic - Simple bucket creation
• With Lifecycle - Lifecycle rules
• Encrypted - KMS encryption
• Complete - All features

Development

Prerequisites

# Install pre-commit
pip install pre-commit
pre-commit install

# Install terraform-docs
brew install terraform-docs

# Install tflint
brew install tflint

Testing

# Validate
terraform validate

# Format
terraform fmt -recursive

# Lint
tflint --init
tflint

# Run tests
cd test && go test -v

Contributing

See CONTRIBUTING.md

License

MIT Licensed. See LICENSE

### CI/CD Pipeline

#### .github/workflows/validate.yml

```yaml
name: Validate

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    name: Terraform Validate
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.6.0

      - name: Terraform Format Check
        run: terraform fmt -check -recursive

      - name: Terraform Init
        run: terraform init -backend=false

      - name: Terraform Validate
        run: terraform validate

  lint:
    name: TFLint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - uses: terraform-linters/setup-tflint@v4
        with:
          tflint_version: latest

      - name: Init TFLint
        run: tflint --init

      - name: Run TFLint
        run: tflint --format compact

  security:
    name: Security Scan
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Checkov
        uses: bridgecrewio/checkov-action@master
        with:
          directory: .
          framework: terraform
          quiet: false
          soft_fail: true

  docs:
    name: Documentation
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}

      - name: Generate Terraform docs
        uses: terraform-docs/[email protected]
        with:
          working-dir: .
          output-file: README.md
          output-method: inject
          git-push: true

  examples:
    name: Validate Examples
    runs-on: ubuntu-latest
    strategy:
      matrix:
        example: [basic, with-lifecycle, encrypted, complete]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3

      - name: Init Example
        run: terraform init -backend=false
        working-directory: examples/${{ matrix.example }}

      - name: Validate Example
        run: terraform validate
        working-directory: examples/${{ matrix.example }}

Pre-commit Configuration

.pre-commit-config.yaml

repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.83.5
    hooks:
      - id: terraform_fmt
        name: Terraform format
        description: Format Terraform files

      - id: terraform_validate
        name: Terraform validate
        description: Validate Terraform configuration

      - id: terraform_docs
        name: Terraform docs
        description: Update documentation
        args:
          - --args=--lockfile=false

      - id: terraform_tflint
        name: TFLint
        description: Lint Terraform files
        args:
          - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl

      - id: terraform_checkov
        name: Checkov
        description: Security scanning
        args:
          - --args=--quiet
          - --args=--framework terraform

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-merge-conflict

Terraform Docs Configuration

.terraform-docs.yml

formatter: "markdown table"

version: ""

header-from: main.tf

content: |-
  {{ .Header }}

  ## Usage

  {{ include "examples/basic/main.tf" }}

  {{ .Requirements }}

  {{ .Providers }}

  {{ .Inputs }}

  {{ .Outputs }}

  ## Examples

  - [Basic](./examples/basic) - Simple bucket creation
  - [With Lifecycle](./examples/with-lifecycle) - Lifecycle rules
  - [Encrypted](./examples/encrypted) - KMS encryption
  - [Complete](./examples/complete) - All features

  {{ .Footer }}

output:
  file: README.md
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: true
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  read-comments: true
  required: true
  sensitive: true
  type: true

TFLint Configuration

.tflint.hcl

plugin "aws" {
  enabled = true
  version = "0.28.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

config {
  module = true
  force = false
}

rule "terraform_naming_convention" {
  enabled = true
}

rule "terraform_documented_variables" {
  enabled = true
}

rule "terraform_documented_outputs" {
  enabled = true
}

rule "terraform_unused_declarations" {
  enabled = true
}

rule "terraform_deprecated_interpolation" {
  enabled = true
}

Additional Examples

examples/encrypted/main.tf

provider "aws" {
  region = "us-east-1"
}

# KMS key for encryption
resource "aws_kms_key" "bucket" {
  description             = "KMS key for S3 bucket encryption"
  deletion_window_in_days = 7
  enable_key_rotation     = true

  tags = {
    Purpose = "S3 Encryption"
  }
}

resource "aws_kms_alias" "bucket" {
  name          = "alias/s3-bucket-key"
  target_key_id = aws_kms_key.bucket.key_id
}

module "encrypted_bucket" {
  source = "../../"

  bucket_name         = "encrypted-data-${var.environment}"
  environment         = var.environment
  versioning_enabled  = true
  block_public_access = true
  kms_key_id          = aws_kms_key.bucket.arn

  tags = {
    Project    = "SecureApp"
    Encryption = "KMS"
  }
}

output "bucket_arn" {
  value = module.encrypted_bucket.bucket_arn
}

output "kms_key_id" {
  value = aws_kms_key.bucket.id
}

examples/complete/main.tf

provider "aws" {
  region = "us-east-1"
}

# Logging bucket
resource "aws_s3_bucket" "logs" {
  bucket = "app-logs-${var.environment}"
}

resource "aws_s3_bucket_acl" "logs" {
  bucket = aws_s3_bucket.logs.id
  acl    = "log-delivery-write"
}

# Complete configuration
module "complete_bucket" {
  source = "../../"

  bucket_name         = "complete-example-${var.environment}"
  environment         = var.environment
  versioning_enabled  = true
  block_public_access = true

  lifecycle_rules = [
    {
      id              = "transition-to-ia"
      enabled         = true
      transition_days = 30
      storage_class   = "STANDARD_IA"
      expiration_days = 0
    },
    {
      id              = "transition-to-glacier"
      enabled         = true
      transition_days = 90
      storage_class   = "GLACIER"
      expiration_days = 0
    },
    {
      id              = "expire-old-data"
      enabled         = true
      transition_days = 0
      storage_class   = "GLACIER"
      expiration_days = 365
    }
  ]

  tags = {
    Project     = "CompleteExample"
    CostCenter  = "Engineering"
    Compliance  = "Required"
  }
}

# Enable logging
resource "aws_s3_bucket_logging" "complete" {
  bucket = module.complete_bucket.bucket_id

  target_bucket = aws_s3_bucket.logs.id
  target_prefix = "access-logs/"
}

output "bucket_arn" {
  value = module.complete_bucket.bucket_arn
}

Explanation

Why These Improvements Matter

1. Automated Validation

Before:

• Manual testing
• Inconsistent formatting
• Missed errors

After:

on: [push, pull_request]  # Automatic validation

• Every change validated
• Consistent standards
• Early error detection

2. Documentation Generation

Manual docs drift over time

Automated docs stay current:

- name: Generate Terraform docs
  uses: terraform-docs/[email protected]

Always reflects actual code.

3. Pre-commit Hooks

Catch issues before commit:

hooks:
  - id: terraform_fmt
  - id: terraform_validate
  - id: terraform_docs

Ensures quality at source.

4. Security Scanning

Checkov finds security issues:

- name: Run Checkov
  uses: bridgecrewio/checkov-action@master

Prevents misconfigurations.

Module Maturity Levels

Level	Features
Basic	Working code, manual testing
Good	Documentation, examples
Better	Validation, formatting
Best	CI/CD, testing, security scans