Skip to content

Commit

Permalink
Enhance README and examples for EKS cluster management
Browse files Browse the repository at this point in the history 
- Updated README to clarify module functionality and features.
- Added centralized management examples for EKS cluster repositories.
- Improved variable definitions for better clarity and usability.
  • Loading branch information
Your Name committed Aug 27, 2025
1 parent 6596ff7 commit e1ebcd8
Show file tree
Hide file tree
Showing 4 changed files with 349 additions and 134 deletions.
249 changes: 132 additions & 117 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
69 changes: 52 additions & 17 deletions examples/basic/main.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

0 comments on commit e1ebcd8

Please sign in to comment.