Skip to content

Commit

Permalink
complete update workflow, fix create workflow, open PRs on both
Browse files Browse the repository at this point in the history
  • Loading branch information
@morga471
morga471 committed Mar 19, 2026
1 parent 3d6f88d commit b6c3b24
Show file tree
Hide file tree
Showing 13 changed files with 332 additions and 2,730 deletions.
236 changes: 122 additions & 114 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,160 +1,170 @@
# terraform-eks-deployment

Terraform module for EKS cluster repository bootstrapping and configuration
Terraform module for bootstrapping and updating EKS cluster configuration repositories.

## Overview

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.
This module manages the GitHub repository that holds your cluster Terragrunt configuration. It renders core files such as `root.hcl`, `account.hcl`, `region.hcl`, `vpc.hcl`, `cluster.hcl`, and selected module `terragrunt.hcl` files from `template-eks-cluster`.

It supports two workflows:

- `create`: create a repository, commit generated files to `new/<cluster_name>`, and open a pull request into `main`
- `update`: manage an existing repository, commit generated files to `update/<cluster_name>`, and open a pull request into `main`

## 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
- Fully Terraform-native workflow
- New-repo and update-repo support
- Automatic working branch creation
- Automatic pull request creation into `main`
- Rendered Terragrunt configuration from module inputs
- Optional syncing of module-specific `terragrunt.hcl` files from `template-eks-cluster`
- Team access management through the underlying GitHub repo module

## Prerequisites

- GitHub token with repository and workflow permissions
- Terraform 1.0.0 or newer
- Access to GitHub Enterprise (if using enterprise version)
- Terraform 1.x
- GitHub token with repository and pull request permissions
- Access to your GitHub Enterprise instance, if applicable

## Usage

### Basic Example
### Create a New Repository

```hcl
module "eks_deployment" {
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"
}
# 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"
}
source = "../../"
# VPC configuration
vpc_config = {
vpc_name = "prod-vpc"
vpc_domain_name = "prod.example.com"
name = "csvd-lab-mcm"
organization = "SCT-Engineering"
repository_mode = "create"
environment = "dev"
region = "us-gov-east-1"
repository_teams = {
"platform-team" = "admin"
"developers" = "push"
}
# 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"
account_name = "lab-dev-gov"
aws_account_id = "224384469011"
environment_abbr = "lab"
vpc_name = "vpc3-lab-dev"
vpc_domain_name = "dev.lab.csp2.census.gov"
cluster_mailing_list = "matthew.c.morgan@census.gov"
finops_project_name = "csvd_platformbaseline"
finops_project_number = "fs0000000078"
finops_project_role = "csvd_platformbaseline_eks"
organization = "census:ocio:csvd"
tags = {
Owner = "Platform Team",
Environment = "Production",
CostCenter = "123-456"
}
module_enablement_overrides = {
cert_manager = true,
prometheus = true,
grafana = true,
istio = true
Owner = "matthew.c.morgan@census.gov"
Environment = "development"
CostCenter = "fs0000000078"
}
}
}
output "repository_url" {
value = module.eks_deployment.repository_url
template_enabled_modules = {
eks-gatekeeper = true
eks-grafana = true
eks-kiali = true
eks-loki = true
eks-otel = true
eks-prometheus = true
eks-tempo = true
}
}
```

### Update an Existing Repository on a PR Branch

Use this mode when the cluster repository already exists and you only want to update managed files on a branch for a pull request.
### Update an Existing Repository

```hcl
module "eks_deployment" {
source = "../../"
name = "csvd-dev-mcm"
organization = "SCT-Engineering"
create_repository = false
files_branch = "update/csvd-dev-mcm"
environment = "dev"
region = "us-gov-east-1"
name = "csvd-lab-mcm"
organization = "SCT-Engineering"
repository_mode = "update"
environment = "dev"
region = "us-gov-east-1"
cluster_config = {
account_name = "csvd-dev-gov"
aws_account_id = "229685449397"
environment_abbr = "dev"
vpc_name = "vpc2-csvd-dev"
vpc_domain_name = "dev.csvd.csp1.census.gov"
cluster_mailing_list = "matthew.c.morgan@census.gov"
account_name = "lab-dev-gov"
aws_account_id = "224384469011"
environment_abbr = "lab"
vpc_name = "vpc3-lab-dev"
vpc_domain_name = "dev.lab.csp2.census.gov"
cluster_mailing_list = "matthew.c.morgan@census.gov"
finops_project_name = "csvd_platformbaseline"
finops_project_number = "fs0000000078"
finops_project_role = "csvd_platformbaseline_eks"
organization = "census:ocio:csvd"
}
template_enabled_modules = {
eks-gatekeeper = true
eks-grafana = true
eks-kiali = true
eks-loki = true
}
}
```

If `files_branch` does not already exist, create it first from your default branch, then run `terraform apply`.
### Template Module Selection

`template_enabled_modules` controls which module-specific `terragrunt.hcl` files are synced from `template-eks-cluster`.

These core cluster modules are always enabled and cannot be turned off:

- `eks`
- `eks-config`
- `eks-karpenter`
- `eks-istio`
- `eks-dns`

By default, this module now attempts to create `files_branch` automatically when `create_repository = false`, using the repository default branch as the source. You can override the source with `files_branch_source_branch`.
Any omitted key is treated as `false` for optional modules.

## Generated Files

The module automatically generates the following files in your new repository:
The module manages files such as:

- `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
- `root.hcl`
- `config.json`
- `README.md`
- `<environment>/account.hcl`
- `<environment>/<region>/region.hcl`
- `<environment>/<region>/vpc/vpc.hcl`
- `<environment>/<region>/vpc/cluster/cluster.hcl`
- `<environment>/<region>/vpc/cluster/<module>/terragrunt.hcl` for enabled template modules
- `_envcommon/default-versions.hcl`
- `_envcommon/common-variables.hcl`
- `_envcommon/prefixes.hcl`

These files are committed directly to your new repository and are ready for use with Terragrunt to deploy your EKS cluster.
## Working Branch and PR Behavior

## Module Configuration
- `repository_mode = "create"` creates branch `new/<name>` and opens a PR to `main`
- `repository_mode = "update"` creates branch `update/<name>` and opens a PR to `main`
- For update mode, the working branch is created from the repository default branch unless `files_branch_source_branch` is provided

### Required Variables
## Key Inputs

| 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 |
### Required

- `name`
- `environment`
- `region`
- `cluster_config`

### Optional Variables
### Common Optional Inputs

| 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"` |
- `organization`
- `repository_mode`
- `repository_teams`
- `template_enabled_modules`
- `files_branch_source_branch`
- `force_name`

For complete configuration options, see the variables.tf file.
See [variables.tf](/apps/terraform/workspaces/morga471/terraform/terraform-eks-deployment/variables.tf) for the full input surface.

## Outputs

Expand All @@ -165,11 +175,9 @@ For complete configuration options, see the variables.tf file.

## How It Works

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.

## Migrating from Previous Workflow

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.
1. The module computes whether it is in create or update mode.
2. It renders repository files from Terraform templates and input variables.
3. It creates or updates the target repository through `terraform-github-repo`.
4. It creates a working branch (`new/<name>` or `update/<name>`).
5. It commits the generated files to that branch.
6. It opens a pull request from that branch into `main`.
47 changes: 0 additions & 47 deletions ROADMAP.md
View file

This file was deleted.

11 changes: 5 additions & 6 deletions clusters/csvd-dev-mcm/main.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,11 @@ module "eks_deployment" {
source = "../../"

# Repository and cluster configuration - single name for both
name = "csvd-dev-mcm"
organization = "SCT-Engineering"
create_repository = false
files_branch = "update/csvd-dev-mcm"
environment = "dev"
region = "us-gov-east-1"
name = "csvd-dev-mcm"
organization = "SCT-Engineering"
repository_mode = "update"
environment = "dev"
region = "us-gov-east-1"

# Cluster configuration - simplified interface
cluster_config = {
Expand Down
23 changes: 23 additions & 0 deletions clusters/csvd-lab-mcm/logs/plan.20260319.1773952402.log
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# starting v1.11.0 action plan file logs/plan.20260319.1773952402.log stamp 20260319.1773952402 time 1773952402
# current_directory=/apps/terraform/workspaces/morga471/terraform/terraform-eks-deployment/clusters/csvd-lab-mcm
# git_repository=git@github.e.it.census.gov:sct-engineering/terraform-eks-deployment
# git_current_branch=test_cluster
# terraform_version=Terraform v0.12.31
# TFCONTROL=
# TF_CLI_CONFIG_FILE=
# TFARGS="" TFNOCLOR= TFNOLOG= TFNOPROXY=
# env TF_VAR_ variables
# TF_VAR_os_environment={"pwd":"/apps/terraform/workspaces/morga471/terraform/terraform-eks-deployment/clusters/csvd-lab-mcm"}
# TF_VAR_os_username=morga471


Error: Error locking state: Error acquiring the state lock: state snapshot was created by Terraform v1.14.7, which is newer than current v0.12.31; upgrade to Terraform v1.14.7 or greater to work with this state

Terraform acquires a state lock to protect the state from being written
by multiple users at the same time. Please resolve the issue above and try
again. For most commands, you can disable locking with the "-lock=false"
flag, but this is not recommended.


# ending v1.11.0 action plan file logs/plan.20260319.1773952402.log stamp 20260319.1773952402 start 1773952402 end 1773952402 elapsed 0

0 comments on commit b6c3b24

Please sign in to comment.