Add comprehensive EKS Cluster Template roadmap and configuration files

.github/workflows/terraform-validate.yaml

@@ -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()

.gitignore

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

README.md

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

ROADMAP.md

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

examples/basic/.terraform/modules/modules.json

@@ -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"}]}

examples/basic/main.tf

@@ -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"
+  }
+}

examples/basic/variables.tf

@@ -0,0 +1,5 @@
+variable "github_token" {
+  description = "GitHub token for API operations"
+  type        = string
+  sensitive   = true
+}