tf-starter 1.0.0

package/tf_starter/templates/aws/misc/README.md.j2

@@ -0,0 +1,445 @@
+# {{ project_name }}
+
+> Infrastructure-as-Code project generated by **tf-starter** for **{{ provider | upper }}**
+
+---
+
+## Architecture
+
+{% if provider == "aws" %}
+```
+                    Internet
+                       |
+{% if "apigateway" in services and "compute" in services %}
+          +------------+------------+
+          |                         |
+  +-------+--------+    +----------+-------+
+  |  API Gateway   |    |       ALB        |
+  +-------+--------+    +----------+-------+
+          |                         |
+  +-------+--------+    +----------+-------+
+  |     Lambda     |    | Auto Scaling EC2 |
+  +-------+--------+    +----------+-------+
+{% elif "apigateway" in services %}
+               +---------------+
+               |  API Gateway  |
+               +---------------+
+                       |
+               +---------------+
+               |    Lambda     |
+               +---------------+
+{% elif "kubernetes" in services and "compute" in services %}
+               +---------------+
+               |      ALB      |
+               +---------------+
+                       |
+          +------------+------------+
+          |                         |
+  +-------+--------+    +----------+-------+
+  |   EKS Cluster  |    | Auto Scaling EC2 |
+  +-------+--------+    +----------+-------+
+{% elif "kubernetes" in services %}
+               +---------------+
+               |      ALB      |
+               +---------------+
+                       |
+               +---------------+
+               |  EKS Cluster  |
+               +---------------+
+{% elif "compute" in services %}
+               +---------------+
+               |      ALB      |
+               +---------------+
+                       |
+               +---------------+
+               | Auto Scaling  |
+               |    EC2        |
+               +---------------+
+{% elif "lambda" in services %}
+               +---------------+
+               |    Lambda     |
+               +---------------+
+{% else %}
+               +---------------+
+               |     VPC       |
+               +---------------+
+{% endif %}
+{% if "database" in services %}
+                       |
+               +---------------+
+               | RDS PostgreSQL|
+               |  (Multi-AZ)  |
+               +---------------+
+{% endif %}
+{% if "messaging" in services %}
+                       |
+               +---------------+
+               |   SQS Queue   |
+               +---------------+
+{% endif %}
+{% if "storage" in services %}
+                       |
+               +---------------+
+               |   S3 Bucket   |
+               +---------------+
+{% endif %}
+```
+{% elif provider == "gcp" %}
+```
+{% if "kubernetes" in services %}
+                    Internet
+                       |
+               +------------------+
+               |  Cloud Load Bal. |
+               +------------------+
+                       |
+               +------------------+
+               |   GKE Cluster    |
+               +------------------+
+{% elif "compute" in services %}
+                    Internet
+                       |
+               +------------------+
+               |  Cloud Load Bal. |
+               +------------------+
+                       |
+               +------------------+
+               |  Managed Inst.   |
+               |     Group        |
+               +------------------+
+{% else %}
+                    Internet
+                       |
+               +------------------+
+               |    VPC Network   |
+               +------------------+
+{% endif %}
+{% if "database" in services %}
+                       |
+               +------------------+
+               |  Cloud SQL       |
+               |  PostgreSQL      |
+               +------------------+
+{% endif %}
+{% if "messaging" in services %}
+                       |
+               +------------------+
+               |   Pub/Sub        |
+               +------------------+
+{% endif %}
+{% if "storage" in services %}
+                       |
+               +------------------+
+               |   GCS Bucket     |
+               +------------------+
+{% endif %}
+```
+{% elif provider == "azure" %}
+```
+{% if "kubernetes" in services %}
+                    Internet
+                       |
+               +------------------+
+               |  App Gateway     |
+               +------------------+
+                       |
+               +------------------+
+               |   AKS Cluster    |
+               +------------------+
+{% elif "compute" in services %}
+                    Internet
+                       |
+               +------------------+
+               |  App Gateway     |
+               +------------------+
+                       |
+               +------------------+
+               |      VMSS        |
+               +------------------+
+{% else %}
+                    Internet
+                       |
+               +------------------+
+               |      VNet        |
+               +------------------+
+{% endif %}
+{% if "database" in services %}
+                       |
+               +------------------+
+               | Azure PostgreSQL |
+               | Flexible Server  |
+               +------------------+
+{% endif %}
+{% if "messaging" in services %}
+                       |
+               +------------------+
+               |   Service Bus    |
+               +------------------+
+{% endif %}
+{% if "storage" in services %}
+                       |
+               +------------------+
+               | Storage Account  |
+               +------------------+
+{% endif %}
+```
+{% endif %}
+
+---
+
+## Project Overview
+
+This project provisions cloud infrastructure on **{{ provider | upper }}** using Terraform.
+It was generated using the `tf-starter` CLI tool and follows enterprise-grade
+infrastructure-as-code best practices.
+
+### Enabled Services
+
+| Service | Status |
+|---------|--------|
+| Network | Enabled (always) |
+{% for svc in services %}
+{% if svc != "network" %}
+| {{ svc | capitalize }} | Enabled |
+{% endif %}
+{% endfor %}
+
+---
+
+## Folder Structure
+
+```
+{{ project_name }}/
+├── environments/           # Per-environment configurations
+{% for env in environments %}
+│   ├── {{ env }}/
+│   │   ├── main.tf
+│   │   ├── variables.tf
+│   │   ├── terraform.tfvars
+{% if enable_backend %}
+│   │   └── backend.tf
+{% endif %}
+{% endfor %}
+├── modules/                # Reusable Terraform modules
+{% for svc in services %}
+│   ├── {{ svc }}/
+{% endfor %}
+├── main.tf                 # Root module composition
+├── providers.tf            # Provider configuration
+├── variables.tf            # Input variables
+├── outputs.tf              # Output values
+├── versions.tf             # Terraform & provider versions
+{% if enable_backend %}
+├── backend.tf              # Remote state backend
+{% endif %}
+├── Makefile                # Automation targets
+├── init.sh                 # Bootstrap script
+└── README.md               # This file
+```
+
+---
+
+## Environments
+
+| Environment | Description |
+|-------------|-------------|
+{% for env in environments %}
+{% if env == "prod" %}
+| **{{ env }}** | Production — HA enabled, deletion protection on, extended backups |
+{% elif env == "staging" %}
+| **{{ env }}** | Staging — mirrors production at reduced scale for pre-release testing |
+{% elif env == "dev" %}
+| **{{ env }}** | Development — minimal resources, fast iteration |
+{% else %}
+| **{{ env }}** | Custom environment |
+{% endif %}
+{% endfor %}
+
+Each environment has its own `terraform.tfvars` file. Edit these to customize
+resource sizing, networking CIDRs, and service-specific parameters.
+
+---
+
+{% if enable_backend %}
+## Remote Backend
+
+This project uses a remote backend for Terraform state:
+
+{% if provider == "aws" %}
+- **State storage:** S3 bucket (`{{ project_name }}-terraform-state`)
+- **State locking:** DynamoDB table (`{{ project_name }}-terraform-lock`)
+{% elif provider == "gcp" %}
+- **State storage:** GCS bucket (`{{ project_name }}-terraform-state`)
+{% elif provider == "azure" %}
+- **State storage:** Azure Storage Account
+{% endif %}
+
+> **Important:** You must create the backend resources before running `terraform init`.
+> Use the `init.sh` script to bootstrap them.
+
+---
+{% endif %}
+
+## Deployment
+
+### Prerequisites
+
+- [Terraform](https://www.terraform.io/downloads) >= 1.6.0
+{% if provider == "aws" %}
+- [AWS CLI](https://aws.amazon.com/cli/) configured with credentials
+{% elif provider == "gcp" %}
+- [Google Cloud SDK](https://cloud.google.com/sdk) with `gcloud auth application-default login`
+{% elif provider == "azure" %}
+- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/) with `az login`
+{% endif %}
+
+### Quick Start
+
+```bash
+# 1. Navigate to your target environment
+cd environments/dev
+
+# 2. Initialize Terraform
+terraform init
+
+# 3. Review the execution plan
+terraform plan
+
+# 4. Apply the changes
+terraform apply
+```
+
+### Using the Makefile
+
+```bash
+# Initialize
+make init
+
+# Plan changes
+make plan
+
+# Apply changes
+make apply
+
+# Format code
+make fmt
+
+# Validate configuration
+make validate
+
+# Destroy infrastructure
+make destroy
+```
+
+---
+
+## Destroy Instructions
+
+```bash
+# Review what will be destroyed
+terraform plan -destroy
+
+# Destroy all resources
+terraform destroy
+
+# Or use Makefile
+make destroy
+```
+
+> **Warning:** Destroying production infrastructure is irreversible. Ensure you
+> have backups and have communicated with your team before proceeding.
+
+---
+
+## Security Considerations
+
+- All data-at-rest is encrypted
+{% if "database" in services %}
+- Database credentials are managed via Terraform (consider using Vault or Secrets Manager)
+- Database is deployed in private subnets only
+{% endif %}
+{% if "storage" in services %}
+- S3/GCS/Blob public access is blocked by default
+{% endif %}
+- Security groups follow the principle of least privilege
+- All resources are tagged for cost allocation and ownership tracking
+{% if enable_backend %}
+- Terraform state is encrypted at rest
+{% endif %}
+
+---
+
+## Scaling
+
+{% if "compute" in services %}
+### Compute
+Adjust `asg_min_size`, `asg_max_size`, and `asg_desired_capacity` in
+your environment's `terraform.tfvars` to scale horizontally.
+{% endif %}
+
+{% if "kubernetes" in services %}
+### Kubernetes
+Adjust `eks_node_min_size`, `eks_node_max_size`, and `eks_node_desired_size`
+to control the cluster node pool. Consider enabling Cluster Autoscaler.
+{% endif %}
+
+{% if "lambda" in services %}
+### Lambda
+- Adjust `lambda_memory_size` (128–10240 MB) — CPU scales proportionally with memory
+- Adjust `lambda_timeout` (1–900 seconds) based on workload
+- For high-throughput, consider reserved concurrency and provisioned concurrency
+{% endif %}
+
+{% if "apigateway" in services %}
+### API Gateway
+- Adjust `apigw_throttle_burst_limit` and `apigw_throttle_rate_limit` for traffic control
+- Use caching to reduce Lambda invocations for repeated requests
+- Consider usage plans and API keys for external consumers
+{% endif %}
+
+{% if "database" in services %}
+### Database
+- Vertical scaling: change `db_instance_class`
+- Storage auto-scaling is enabled (up to 2x allocated storage)
+- Production uses Multi-AZ for high availability
+{% endif %}
+
+---
+
+## Adding New Modules
+
+1. Create a new directory under `modules/`:
+   ```bash
+   mkdir -p modules/my-module
+   ```
+
+2. Add `main.tf`, `variables.tf`, and `outputs.tf` inside it.
+
+3. Reference it in the root `main.tf`:
+   ```hcl
+   module "my_module" {
+     source = "./modules/my-module"
+     # pass variables
+   }
+   ```
+
+4. Add corresponding variables to `variables.tf` and outputs to `outputs.tf`.
+
+---
+
+## Customizing Variables
+
+1. Open the relevant environment's `terraform.tfvars` file.
+2. Override any variable defined in `variables.tf`.
+3. Run `terraform plan` to preview changes.
+4. Run `terraform apply` to apply.
+
+For sensitive values, use environment variables:
+```bash
+export TF_VAR_db_username="admin"
+terraform plan
+```
+
+---
+
+*Generated by [tf-starter](https://github.com/tf-starter) v1.0.0*

package/tf_starter/templates/aws/misc/init.sh.j2

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------------------------------------------------
+# Bootstrap script for {{ project_name }}
+# Creates remote backend resources (if enabled) and initializes Terraform.
+# Generated by tf-starter
+# ---------------------------------------------------------------------------------------------------------------------
+
+set -euo pipefail
+
+PROJECT_NAME="{{ project_name }}"
+REGION="{{ region }}"
+
+echo "============================================="
+echo "  {{ project_name }} — Infrastructure Bootstrap"
+echo "============================================="
+echo ""
+
+{% if enable_backend %}
+{% if provider == "aws" %}
+# ----- Create S3 bucket for Terraform state -----
+
+BUCKET_NAME="${PROJECT_NAME}-terraform-state"
+TABLE_NAME="${PROJECT_NAME}-terraform-lock"
+
+echo "Creating S3 bucket for Terraform state: ${BUCKET_NAME}"
+if aws s3api head-bucket --bucket "${BUCKET_NAME}" 2>/dev/null; then
+    echo "  Bucket already exists. Skipping."
+else
+    aws s3api create-bucket \
+        --bucket "${BUCKET_NAME}" \
+        --region "${REGION}" \
+        $([ "${REGION}" != "us-east-1" ] && echo "--create-bucket-configuration LocationConstraint=${REGION}")
+
+    aws s3api put-bucket-versioning \
+        --bucket "${BUCKET_NAME}" \
+        --versioning-configuration Status=Enabled
+
+    aws s3api put-bucket-encryption \
+        --bucket "${BUCKET_NAME}" \
+        --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}'
+
+    aws s3api put-public-access-block \
+        --bucket "${BUCKET_NAME}" \
+        --public-access-block-configuration "BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true"
+
+    echo "  Bucket created."
+fi
+
+# ----- Create DynamoDB table for state locking -----
+
+echo "Creating DynamoDB table for state locking: ${TABLE_NAME}"
+if aws dynamodb describe-table --table-name "${TABLE_NAME}" --region "${REGION}" >/dev/null 2>&1; then
+    echo "  Table already exists. Skipping."
+else
+    aws dynamodb create-table \
+        --table-name "${TABLE_NAME}" \
+        --attribute-definitions AttributeName=LockID,AttributeType=S \
+        --key-schema AttributeName=LockID,KeyType=HASH \
+        --billing-mode PAY_PER_REQUEST \
+        --region "${REGION}"
+
+    echo "  Table created."
+fi
+{% elif provider == "gcp" %}
+BUCKET_NAME="${PROJECT_NAME}-terraform-state"
+
+echo "Creating GCS bucket for Terraform state: ${BUCKET_NAME}"
+if gsutil ls -b "gs://${BUCKET_NAME}" 2>/dev/null; then
+    echo "  Bucket already exists. Skipping."
+else
+    gsutil mb -l "${REGION}" "gs://${BUCKET_NAME}"
+    gsutil versioning set on "gs://${BUCKET_NAME}"
+    echo "  Bucket created."
+fi
+{% elif provider == "azure" %}
+RESOURCE_GROUP="${PROJECT_NAME}-tfstate-rg"
+STORAGE_ACCOUNT=$(echo "${PROJECT_NAME}tfstate" | tr -d '-' | head -c 24)
+CONTAINER_NAME="tfstate"
+
+echo "Creating Azure Storage for Terraform state..."
+az group create --name "${RESOURCE_GROUP}" --location "${REGION}" || true
+
+az storage account create \
+    --resource-group "${RESOURCE_GROUP}" \
+    --name "${STORAGE_ACCOUNT}" \
+    --sku Standard_LRS \
+    --encryption-services blob 2>/dev/null || echo "  Storage account already exists."
+
+az storage container create \
+    --name "${CONTAINER_NAME}" \
+    --account-name "${STORAGE_ACCOUNT}" 2>/dev/null || echo "  Container already exists."
+{% endif %}
+
+echo ""
+{% endif %}
+
+# ----- Initialize Terraform -----
+
+echo "Initializing Terraform..."
+for env_dir in environments/*/; do
+    env_name=$(basename "${env_dir}")
+    echo "  Initializing environment: ${env_name}"
+    (cd "${env_dir}" && terraform init)
+done
+
+echo ""
+echo "============================================="
+echo "  Bootstrap complete!"
+echo "  Run 'make plan ENV=dev' to preview changes."
+echo "============================================="

package/tf_starter/templates/aws/misc/pre-commit-config.yaml.j2

@@ -0,0 +1,34 @@
+# Pre-commit configuration for {{ project_name }}
+# Install: pip install pre-commit && pre-commit install
+# Generated by tf-starter
+
+repos:
+  - repo: https://github.com/antonbabenko/pre-commit-terraform
+    rev: v1.88.0
+    hooks:
+      - id: terraform_fmt
+        name: Terraform fmt
+        description: Rewrites Terraform config to canonical format
+
+      - id: terraform_validate
+        name: Terraform validate
+        description: Validates Terraform configuration
+        args:
+          - --hook-config=--retry-once-with-cleanup=true
+
+      - id: terraform_tflint
+        name: Terraform tflint
+        description: Lints Terraform configuration
+
+      - id: terraform_docs
+        name: Terraform docs
+        description: Generates documentation from Terraform modules
+
+  - 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-merge-conflict
+      - id: detect-private-key