diff --git a/README.md b/README.md index 282aa3a..5b36df3 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,180 @@ # terraform-eks-deployment -Terraform module for EKS cluster deployment and configuration +Terraform module for EKS cluster repository bootstrapping and configuration ## Overview -This module creates a new GitHub repository for your EKS cluster based on the template-eks-cluster repository. It sets up all necessary configuration files and triggers automated workflows for cluster deployment. +This module creates and configures a new GitHub repository for your EKS cluster based on the template-eks-cluster repository. It automatically generates all necessary Terragrunt HCL files (`root.hcl`, `account.hcl`, `region.hcl`, etc.) directly from your input variables, eliminating the need for manual configuration or separate Ansible playbooks. + +## Features + +- **Fully Terraform-Native**: No Lambda functions, Ansible playbooks, or manual steps required +- **Complete HCL Generation**: Automatically creates all necessary Terragrunt HCL files +- **Team Management**: Configures repository permissions for your teams +- **Customizable**: Extensive configuration options for cluster, account, and VPC settings ## Prerequisites - GitHub token with repository and workflow permissions -- Python 3.x installed on the machine running Terraform +- Terraform 1.0.0 or newer - Access to GitHub Enterprise (if using enterprise version) ## Usage +### Basic Example + ```hcl module "eks_deployment" { - source = "path/to/terraform-eks-deployment" - - name = "my-eks-cluster" - organization = "my-org" - environment = "production" - region = "us-east-1" + source = "github.com/HappyPathway/terraform-eks-deployment" + + # Repository configuration + repository_name = "eks-prod-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "devops-team" = "maintain", + "developers" = "push" + } - cluster_config = { - cluster_name = "prod-eks-01" - account_name = "prod-account" - aws_account_id = "123456789012" - aws_profile = "prod-profile" + # Basic settings + organization = "my-org" + environment = "production" + region = "us-gov-west-1" + github_server_url = "https://github.e.it.census.gov" # For GitHub Enterprise + + # Account configuration + account_config = { + account_name = "prod-account" + aws_account_id = "123456789012" environment_abbr = "prod" + } + + # VPC configuration + vpc_config = { vpc_name = "prod-vpc" vpc_domain_name = "prod.example.com" } - github_token = "your-github-token" - github_server_url = "https://github.e.it.census.gov" # Optional, for GitHub Enterprise + # Cluster configuration + cluster_config = { + cluster_name = "prod-eks-01" + cluster_mailing_list = "team@example.com" + eks_instance_disk_size = 200 + eks_ng_desired_size = 5 + eks_ng_max_size = 10 + eks_ng_min_size = 3 + organization = "census:ocio:csvd" + finops_project_name = "csvd_platformbaseline" + finops_project_number = "fs0000000078" + finops_project_role = "csvd_platformbaseline_app" + tags = { + Owner = "Platform Team", + Environment = "Production", + CostCenter = "123-456" + } + module_enablement_overrides = { + cert_manager = true, + prometheus = true, + grafana = true, + istio = true + } + } } -``` - -## Workflow Automation - -### Overview - -The module automatically triggers GitHub Actions workflows in your newly created repository to: -1. Install Python requirements -2. Execute Terragrunt operations for cluster management - -### Workflow Sequence - -1. **Repository Creation**: The module creates a new repository from the template-eks-cluster template -2. **Initial Configuration**: Configuration files are generated based on your inputs -3. **Requirements Installation**: A workflow is triggered to install Python dependencies -4. **Cluster Planning**: A terragrunt plan workflow is automatically triggered - -### Available Workflows -Your new repository will have these workflows available: - -1. **Install Requirements** (`install-requirements.yml`) - - Triggered automatically on repository creation - - Installs all Python dependencies from requirements.txt - -2. **Terragrunt Cluster Operations** (`terragrunt-cluster-build.yml`) - - Supports plan, apply, and destroy operations - - Can be triggered manually or via API - - Includes safety checks and approvals - -### Triggering Workflows - -The workflows can be triggered in two ways: +output "repository_url" { + value = module.eks_deployment.repository_url +} +``` -1. **Automatic Triggering** - - On repository creation, the module automatically triggers: - 1. Requirements installation - 2. Initial cluster plan +### Centralized Management Example -2. **Manual Triggering** - - Via GitHub UI: - 1. Go to Actions tab - 2. Select desired workflow - 3. Click "Run workflow" - 4. Fill in parameters +You can use this module to manage multiple EKS cluster repositories from a central location: -3. **API Triggering** - - Use GitHub's API to trigger workflows: - ```bash - curl -X POST \ - -H "Authorization: Bearer $GITHUB_TOKEN" \ - -H "Accept: application/vnd.github.v3+json" \ - "https://api.github.com/repos/OWNER/REPO/dispatches" \ - -d '{ - "event_type": "cluster-plan", - "client_payload": { - "environment": "dev", - "region": "us-east-1", - "cluster_dir": "my-cluster", - "auto_approve": false - } - }' - ``` +```hcl +# Production EKS Cluster Repository +module "prod_eks_cluster" { + source = "github.com/HappyPathway/terraform-eks-deployment" + + repository_name = "eks-prod-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "prod-sre-team" = "maintain" + } + + # ...other configuration omitted for brevity +} -### Supported Events +# Development EKS Cluster Repository +module "dev_eks_cluster" { + source = "github.com/HappyPathway/terraform-eks-deployment" -The following event types are supported for workflow triggers: + repository_name = "eks-dev-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "dev-team" = "maintain" + } + + # ...other configuration omitted for brevity +} +``` -- `install-requirements`: Install Python dependencies -- `cluster-plan`: Preview cluster changes -- `cluster-apply`: Apply cluster changes -- `cluster-destroy`: Destroy cluster +## Generated Files -### Required Secrets +The module automatically generates the following files in your new repository: -The following secrets must be configured in your repository: +- `root.hcl`: Global Terragrunt configuration +- `[environment]/account.hcl`: Account-specific variables +- `[environment]/[region]/region.hcl`: Region-specific variables +- `[environment]/[region]/vpc/vpc.hcl`: VPC-specific variables +- `[environment]/[region]/vpc/[cluster_name]/cluster.hcl`: Cluster-specific variables +- `README.md`: Usage instructions and documentation -- `AWS_ROLE_ARN`: ARN of the AWS role to assume -- `GITHUB_TOKEN`: GitHub token with workflow permissions +These files are committed directly to your new repository and are ready for use with Terragrunt to deploy your EKS cluster. ## Module Configuration ### Required Variables -- `name`: Repository name -- `organization`: GitHub organization name -- `environment`: Deployment environment -- `region`: AWS region -- `cluster_config`: Cluster configuration object -- `github_token`: GitHub token for workflow operations +| Name | Description | +|------|-------------| +| `repository_name` | Name of the GitHub repository to create | +| `organization` | GitHub organization name | +| `environment` | Deployment environment (e.g., production, development) | +| `region` | AWS region for the EKS cluster | +| `account_config` | Map of account configuration values | +| `vpc_config` | Map of VPC configuration values | +| `cluster_config` | Map of cluster configuration values | ### Optional Variables -- `github_server_url`: GitHub Enterprise server URL -- `template_repo_org`: Organization containing the template repository -- `enable_modules`: Map of modules to enable in the cluster +| Name | Description | Default | +|------|-------------|---------| +| `repository_template_owner` | Owner of the template repository | `"HappyPathway"` | +| `repository_template` | Template repository name | `"template-eks-cluster"` | +| `repository_teams` | Map of team names and permission levels | `{}` | +| `github_server_url` | GitHub Enterprise server URL | `"https://api.github.com"` | -For more configuration options, see the variables.tf file. +For complete configuration options, see the variables.tf file. ## Outputs -- `repository_url`: URL of the created repository -- `ssh_clone_url`: SSH clone URL of the repository - -## Security Considerations - -1. **GitHub Token**: Use a token with minimal required permissions -2. **AWS Role**: Use role-based access with least privilege -3. **Auto-approve**: Use with caution in production environments -4. **Environment Protection**: Configure branch protection rules - -## Troubleshooting +| Name | Description | +|------|-------------| +| `repository_url` | URL of the created repository | +| `ssh_clone_url` | SSH clone URL of the repository | -Common issues and solutions: +## How It Works -1. **Workflow Trigger Failures** - - Check GitHub token permissions - - Verify GitHub Enterprise URL (if applicable) - - Check network connectivity +1. The module calls the `terraform-github-repo` module to create a new repository based on your template. +2. It uses Terraform's `templatefile()` function to render Terragrunt HCL files from templates. +3. These rendered files are committed directly to the repository using the `github_repository_file` resource. +4. Team permissions are configured using the `github_team_repository` resource. -2. **Python Requirements** - - Ensure requirements.txt exists in template repository - - Check Python version compatibility +## Migrating from Previous Workflow -3. **AWS Authentication** - - Verify AWS role ARN - - Check AWS credentials configuration +This module replaces the previous Lambda/Ansible-based workflow with a purely Terraform-native approach. If you were previously using the template-automation-lambda to create repositories and then running an Ansible playbook to generate HCL files, you can now accomplish the entire process with just this module. diff --git a/examples/basic/main.tf b/examples/basic/main.tf index 860a3c3..8a43420 100644 --- a/examples/basic/main.tf +++ b/examples/basic/main.tf @@ -7,32 +7,67 @@ provider "github" { module "eks_deployment" { source = "../../" - name = "eks-test-cluster" - organization = "my-org" - environment = "dev" - region = "us-east-1" + # Repository configuration + repository_name = "eks-test-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "devops-team" = "maintain", + "developers" = "push" + } - template_repo_org = "my-org" + # Basic settings + organization = "my-org" + environment = "dev" + region = "us-east-1" github_server_url = "https://github.e.it.census.gov" - cluster_config = { - cluster_name = "dev-eks-01" + # Account configuration + account_config = { account_name = "dev-account" aws_account_id = "123456789012" - aws_profile = "dev-profile" environment_abbr = "dev" - vpc_name = "dev-vpc" - vpc_domain_name = "dev.example.com" } - enable_modules = { - cert_manager = true - prometheus = true - grafana = true + # VPC configuration + vpc_config = { + vpc_name = "dev-vpc" + vpc_domain_name = "dev.example.com" } - versions = { - cluster_version = "1.27" - eks_module_version = "20.33.1" + # Cluster configuration + cluster_config = { + cluster_name = "dev-eks-01" + cluster_mailing_list = "team@example.com" + eks_instance_disk_size = 100 + eks_ng_desired_size = 3 + eks_ng_max_size = 6 + eks_ng_min_size = 2 + organization = "census:ocio:csvd" + finops_project_name = "csvd_platformbaseline" + finops_project_number = "fs0000000078" + finops_project_role = "csvd_platformbaseline_app" + tags = { + Owner = "Platform Team", + Environment = "Development", + CostCenter = "123-456" + } + module_enablement_overrides = { + cert_manager = true, + prometheus = true, + grafana = true, + istio = false + } } +} + +output "repository_url" { + description = "URL of the created GitHub repository" + value = module.eks_deployment.repository_url +} + +output "ssh_clone_url" { + description = "SSH clone URL of the repository" + value = module.eks_deployment.ssh_clone_url } \ No newline at end of file diff --git a/examples/centralized-management/main.tf b/examples/centralized-management/main.tf new file mode 100644 index 0000000..014e335 --- /dev/null +++ b/examples/centralized-management/main.tf @@ -0,0 +1,142 @@ +# Example: Centralized EKS Repository Management +# +# This example demonstrates how to use the terraform-eks-deployment module +# to manage multiple EKS cluster repositories from a central location. + +provider "github" { + # Configuration expected from environment variables: + # GITHUB_TOKEN + # GITHUB_OWNER (optional) + + # For GitHub Enterprise Server + base_url = var.github_server_url +} + +# Production EKS Cluster Repository +module "prod_eks_cluster" { + source = "../../" + + # Repository configuration + repository_name = "eks-prod-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "prod-sre-team" = "maintain", + "developers" = "triage" + } + + # Basic settings + organization = var.github_organization + environment = "production" + region = "us-gov-west-1" + github_server_url = var.github_server_url + + # Account configuration + account_config = { + account_name = "prod-account" + aws_account_id = var.prod_account_id + environment_abbr = "prod" + } + + # VPC configuration + vpc_config = { + vpc_name = "prod-vpc" + vpc_domain_name = "prod.example.com" + } + + # Cluster configuration + cluster_config = { + cluster_name = "prod-eks-01" + cluster_mailing_list = "prod-alerts@example.com" + eks_instance_disk_size = 200 + eks_ng_desired_size = 5 + eks_ng_max_size = 10 + eks_ng_min_size = 3 + organization = "census:ocio:csvd" + finops_project_name = "csvd_platformbaseline" + finops_project_number = "fs0000000078" + finops_project_role = "csvd_platformbaseline_app" + tags = { + Owner = "Platform Team", + Environment = "Production", + CostCenter = "123-456" + } + module_enablement_overrides = { + cert_manager = true, + prometheus = true, + grafana = true, + istio = true + } + } +} + +# Development EKS Cluster Repository +module "dev_eks_cluster" { + source = "../../" + + # Repository configuration + repository_name = "eks-dev-cluster" + repository_template_owner = "HappyPathway" + repository_template = "template-eks-cluster" + repository_teams = { + "platform-team" = "admin", + "dev-team" = "maintain", + "developers" = "push" + } + + # Basic settings + organization = var.github_organization + environment = "development" + region = "us-gov-west-1" + github_server_url = var.github_server_url + + # Account configuration + account_config = { + account_name = "dev-account" + aws_account_id = var.dev_account_id + environment_abbr = "dev" + } + + # VPC configuration + vpc_config = { + vpc_name = "dev-vpc" + vpc_domain_name = "dev.example.com" + } + + # Cluster configuration + cluster_config = { + cluster_name = "dev-eks-01" + cluster_mailing_list = "dev-alerts@example.com" + eks_instance_disk_size = 100 + eks_ng_desired_size = 2 + eks_ng_max_size = 5 + eks_ng_min_size = 1 + organization = "census:ocio:csvd" + finops_project_name = "csvd_platformbaseline" + finops_project_number = "fs0000000078" + finops_project_role = "csvd_platformbaseline_app" + tags = { + Owner = "Platform Team", + Environment = "Development", + CostCenter = "123-456" + } + module_enablement_overrides = { + cert_manager = true, + prometheus = true, + grafana = false, + istio = false + } + } +} + +# Output repository URLs +output "prod_repository_url" { + description = "URL of the production EKS cluster repository" + value = module.prod_eks_cluster.repository_url +} + +output "dev_repository_url" { + description = "URL of the development EKS cluster repository" + value = module.dev_eks_cluster.repository_url +} \ No newline at end of file diff --git a/examples/centralized-management/variables.tf b/examples/centralized-management/variables.tf new file mode 100644 index 0000000..9522f71 --- /dev/null +++ b/examples/centralized-management/variables.tf @@ -0,0 +1,23 @@ +variable "github_organization" { + description = "GitHub organization name" + type = string + default = "HappyPathway" +} + +variable "github_server_url" { + description = "GitHub Enterprise server URL (e.g., https://github.e.it.census.gov)" + type = string + default = "https://api.github.com" +} + +variable "prod_account_id" { + description = "AWS account ID for production" + type = string + default = "123456789012" +} + +variable "dev_account_id" { + description = "AWS account ID for development" + type = string + default = "210987654321" +} \ No newline at end of file