Skip to content

Add comprehensive EKS Cluster Template roadmap and configuration files #1

Merged
merged 15 commits into from
Apr 14, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .github/workflows/terraform-validate.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,20 @@ jobs:
uses: CSVD/gh-actions-setup-terraform@v2
with:
terraform_version: '1.7.3'


- name: Setup GITHUB Credentials
id: github_credentials
uses: CSVD/gh-auth@main
with:
github_app_pem_file: ${{ secrets.GH_APP_PEM_FILE }}
github_app_installation_id: ${{ vars.GH_APP_INSTALLATION_ID }}
github_app_id: ${{ vars.GH_APP_ID }}

- name: Validate Terraform Configuration
id: validate
uses: CSVD/terraform-validate@main
env:
GITHUB_TOKEN: ${{ steps.github_credentials.outputs.github_token }}

- name: Check Validation/Test Results
if: always()
Expand Down
34 changes: 34 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Local .terraform directories
**/.terraform/*

# .tfstate files
*.tfstate
*.tfstate.*

# Crash log files
crash.log
crash.*.log

# Exclude all .tfvars files, which are likely to contain sensitive data
*.tfvars
*.tfvars.json

# Ignore override files as they are usually used for local development
override.tf
override.tf.json
*_override.tf
*_override.tf.json

# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
*tfplan*

# Ignore CLI configuration files
.terraformrc
terraform.rc

# Ignore lock files
.terraform.lock.hcl

# Ignore test temporary files
*.tftest.hcl.tmp
terraform_data_dirs
163 changes: 163 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,165 @@
# terraform-eks-deployment

Terraform module for EKS cluster deployment 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.

## Prerequisites

- GitHub token with repository and workflow permissions
- Python 3.x installed on the machine running Terraform
- Access to GitHub Enterprise (if using enterprise version)

## Usage

```hcl
module "eks_deployment" {
source = "path/to/terraform-eks-deployment"
name = "my-eks-cluster"
organization = "my-org"
environment = "production"
region = "us-east-1"
cluster_config = {
cluster_name = "prod-eks-01"
account_name = "prod-account"
aws_account_id = "123456789012"
aws_profile = "prod-profile"
environment_abbr = "prod"
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
}
```

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

1. **Automatic Triggering**
- On repository creation, the module automatically triggers:
1. Requirements installation
2. Initial cluster plan

2. **Manual Triggering**
- Via GitHub UI:
1. Go to Actions tab
2. Select desired workflow
3. Click "Run workflow"
4. Fill in parameters

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
}
}'
```

### Supported Events

The following event types are supported for workflow triggers:

- `install-requirements`: Install Python dependencies
- `cluster-plan`: Preview cluster changes
- `cluster-apply`: Apply cluster changes
- `cluster-destroy`: Destroy cluster

### Required Secrets

The following secrets must be configured in your repository:

- `AWS_ROLE_ARN`: ARN of the AWS role to assume
- `GITHUB_TOKEN`: GitHub token with workflow permissions

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

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

For more 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

Common issues and solutions:

1. **Workflow Trigger Failures**
- Check GitHub token permissions
- Verify GitHub Enterprise URL (if applicable)
- Check network connectivity

2. **Python Requirements**
- Ensure requirements.txt exists in template repository
- Check Python version compatibility

3. **AWS Authentication**
- Verify AWS role ARN
- Check AWS credentials configuration
62 changes: 62 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# EKS Cluster Template Roadmap

## Current Architecture
- Template repository (`template-eks-cluster`) serves as the base for creating new EKS cluster configurations
- Uses Terraform GitHub repo module to create new repositories from the template
- Implements managed and non-managed extra files functionality
- Supports configuration through `config.json`

## Planned Enhancements

### 1. Automated Cluster Setup (High Priority)
- [x] Add GitHub Actions workflows with workflow_dispatch triggers
- [x] Implement automated terragrunt command execution for cluster building
- [x] Support for plan/apply/destroy commands
- [x] Environment-specific execution
- [x] Automated testing framework
- [ ] Configure workflows to run on specific runners for credential management
- [ ] Create templatized GitHub Actions workflow files
- [ ] Enable direct cluster creation without manual repository cloning

### 2. File Management System (Medium Priority)
- [ ] Implement wrapper module for repo module
- [ ] Add support for crafting and injecting various configuration files
- [ ] Define file lifecycle management strategy
- [ ] Managed files (controlled by workspace)
- [ ] Non-managed files (user-modifiable)

### 3. Version Management (Medium Priority)
- [ ] Implement version control strategy for `default-versions.hcl`
- [ ] Create system for managing platform release versions
- [ ] Set up version override mechanism
- [ ] Default versions in template repo
- [ ] Override capability in workspace creating repos

### 4. Configuration Management (Low Priority)
- [ ] Enhance Makefile and Ansible playbook integration
- [ ] Improve configuration file templating
- [ ] Add validation for configuration files

## Technical Considerations
1. File Lifecycle Management:
- Managed files: Controlled by workspace
- Non-managed files: User-modifiable post-creation
- Version-specific files: Platform release coordination

2. Automation Requirements:
- GitHub Actions runner configuration
- Credential management
- Workflow templating
- Terragrunt integration

3. Version Control Strategy:
- Module version collections
- Platform release versions
- Override mechanisms

## Success Criteria
- Fully automated cluster creation process
- Minimal manual intervention required
- Proper version management system
- Clear file lifecycle management
- Secure credential handling
Submodule eks_deployment.github_repo added at b6b6cb
1 change: 1 addition & 0 deletions examples/basic/.terraform/modules/modules.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"Modules":[{"Key":"","Source":"","Dir":"."},{"Key":"eks_deployment","Source":"../..","Dir":"../.."},{"Key":"eks_deployment.github_repo","Source":"registry.terraform.io/HappyPathway/repo/github","Version":"1.0.83","Dir":".terraform/modules/eks_deployment.github_repo"}]}
38 changes: 38 additions & 0 deletions examples/basic/main.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
provider "github" {
# Configuration expected from environment variables:
# GITHUB_TOKEN
# GITHUB_OWNER (optional)
}

module "eks_deployment" {
source = "../../"

name = "eks-test-cluster"
organization = "my-org"
environment = "dev"
region = "us-east-1"

template_repo_org = "my-org"
github_server_url = "https://github.e.it.census.gov"

cluster_config = {
cluster_name = "dev-eks-01"
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
}

versions = {
cluster_version = "1.27"
eks_module_version = "20.33.1"
}
}
5 changes: 5 additions & 0 deletions examples/basic/variables.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
variable "github_token" {
description = "GitHub token for API operations"
type = string
sensitive = true
}
Loading
Loading