diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..5de6994 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,133 @@ +# GitHub Copilot Instructions — terraform-eks-deployment + +## Project Context + +This is the **Terraform workspace** that creates EKS cluster GitHub repositories as part of the +EKS Cluster Automation (ECA) system. It is run by a CodeBuild project (`eks-terragrunt-repo-creator`) +triggered at runtime by the `eks-terragrunt-repo-gen-template-automation` Lambda function. + +--- + +## Architecture: Lambda → CodeBuild → Terraform + +EKS cluster repos are created via this chain: + +``` +SC Console → CFN Stack → Custom::GitHubRepository + → Lambda (eks-terragrunt-repo-gen-template-automation) + → CodeBuild project (eks-terragrunt-repo-creator) ← this repo runs here + → git clone terraform-eks-deployment (REPO_BRANCH) + → terraform init (providers from registry.terraform.io via Census proxy) + → terraform apply -auto-approve + → CSVD/terraform-github-repo module: + → Creates GHE repo from template-eks-cluster + → Writes 8 rendered Terragrunt HCL files via managed_extra_files + → Opens pull request (repo-init → main) + → Lambda polls build → fetches PR URL → cfn-response SUCCESS +``` + +### CodeBuild environment + +CodeBuild runs on `aws/codebuild/amazonlinux2-x86_64-standard:3.0` (Amazon Linux 2). +Key env vars injected by the Lambda at build-start time: + +| Variable | Source | Purpose | +|----------|--------|---------| +| `GITHUB_TOKEN` | Secrets Manager `ghe-runner/github-token` (PAT, `ghp_`) | Terraform GitHub provider auth; git clone | +| `TF_VAR_name` | CFN input `project_name` | Repo name | +| `TF_VAR_environment` | CFN input `environment` | e.g. `dev` | +| `TF_VAR_region` | CFN input `aws_region` | e.g. `us-gov-west-1` | +| `TF_VAR_cluster_config` | JSON-encoded EKS fields | `vpc_name`, `vpc_domain_name`, `cluster_name`, etc. | +| `TF_VAR_finops` | JSON-encoded FinOps fields | project name/number | +| `GITHUB_OWNER` | `SCT-Engineering` | GitHub org for provider | +| `GITHUB_BASE_URL` | `https://github.e.it.census.gov` | GHE API base URL | + +The buildspec is inlined from this repo's `buildspec.yml` into the +`aws_codebuild_project.eks_repo_creator` resource in `lambda-template-repo-generator/deploy/main.tf`. +After editing `buildspec.yml`, run `tf apply` in `lambda-template-repo-generator/deploy/` to update. + +--- + +## Key Files + +| File | Purpose | +|------|--------| +| `buildspec.yml` | CodeBuild build steps: install Terraform + Census CA cert, clone repo, tf init + apply | +| `main.tf` | Module call to `CSVD/terraform-github-repo`; `managed_extra_files` with rendered HCL | +| `providers.tf` | GitHub provider config (`>= 6.11.0`, `insecure = true`) + AWS provider | +| `variables.tf` | All TF_VAR_* inputs from CodeBuild env (name, environment, region, cluster_config, finops) | +| `locals.tf` | Decodes `cluster_config` JSON; resolves HCL template content | +| `defaults.tf` | Default values for template repo org, template name, org name | +| `callnotes.md` | Session notes and fix log | + +--- + +## SC Product Deployment Methods + +There are **two ways** to deploy the EKS Terragrunt Repository Creator SC product: + +### Method 1: Direct Terraform via `lambda-template-repo-generator/deploy/` ✅ Use this for testing/debugging + +```bash +cd lambda-template-repo-generator/deploy +tf init +tf apply +``` + +Deploys Lambda + CodeBuild project + SC portfolio/product + constraints directly from Terraform state. +Use as the **reference deployment** to validate changes before touching the census pipeline. +Current IDs (us-gov-west-1, account 229685449397): +- Portfolio: `port-h5qd63hw5yagq` (`eks-terragrunt-github-automation`) +- Product: `prod-lmua4oknugafg` (`eks-terragrunt-eks-repo-creator`) + +### Method 2: `terraform-service-catalog-census` Terragrunt (production path) + +```bash +cd terraform-service-catalog-census/non-prod/csvd-dev/west/service-catalog +tf apply # (via terragrunt) +``` + +Census-managed production deployment. Template source: +`terraform-service-catalog-census/templates/products/eks-terragrunt-repo/2-0-0.yaml` + +Always verify Method 1 works first when debugging a census deployment issue. + +--- + +## Key Resources + +| Resource | Location | Purpose | +|----------|----------|---------| +| Lambda | `eks-terragrunt-repo-gen-template-automation` (us-gov-west-1, 229685449397) | CFN Custom Resource handler; starts CodeBuild | +| CodeBuild (repo creation) | `eks-terragrunt-repo-creator` | Runs this workspace via tf apply | +| CodeBuild (image build) | `eks-terragrunt-repo-generator-builder` | Builds Lambda container via packer | +| S3 assets bucket | `csvd-packer-pipeline-assets` | Terraform binary, Census CA cert, Packer binary | +| GitHub token (Terraform) | Secrets Manager `ghe-runner/github-token` | PAT (`ghp_`) for Terraform GitHub provider | +| GitHub token (Lambda) | Secrets Manager `/eks-cluster-deployment/github_token` | App token (`ghs_`) for Lambda Python API calls | +| CSVD TF module | `https://github.e.it.census.gov/CSVD/terraform-github-repo` | Creates repo + files + PR | +| Census SC product template | `terraform-service-catalog-census/templates/products/eks-terragrunt-repo/2-0-0.yaml` | Live SC product CFN template | +| Canonical SC product template | `lambda-template-repo-generator/service-catalog/product-template.yaml` | Reference/source of truth | + +--- + +## Important Runtime Notes + +- **Terraform binary** is installed from `s3://csvd-packer-pipeline-assets/terraform/terraform_1.9.1_linux_amd64.zip` in the INSTALL phase — `releases.hashicorp.com` is blocked on the Census network +- **Census CA cert** is installed from `s3://csvd-packer-pipeline-assets/certs/census-ca.pem` via `update-ca-trust` — required for TLS to `github.e.it.census.gov` +- **Census proxy** `http://proxy.tco.census.gov:3128` must be set as `HTTPS_PROXY`/`HTTP_PROXY` — required for `registry.terraform.io` provider downloads +- **`github.e.it.census.gov`** must be in `NO_PROXY` — direct connection (not via proxy) +- **GitHub provider version** must be `>= 6.11.0` — required by `CSVD/terraform-github-repo` module's `~> 6.11` constraint +- **`provider "github" { insecure = true }`** in `providers.tf` — belt-and-suspenders for TLS +- Pass `vpc_name` (string) — **not** `vpc_id` — or `is_eks_deployment` in the Lambda returns `False` + +--- + +## What NOT to Do + +- ❌ Do not switch back to a Lambda-Python-only repo creation approach — all repo creation must run through CodeBuild + this Terraform workspace (single maintenance point) +- ❌ Do not use `HappyPathway/terraform-github-repo` **public** module — pins `github ~> 6.0`, conflicts with `>= 6.6.0` requirement +- ✅ DO use `CSVD/terraform-github-repo` (https://github.e.it.census.gov/CSVD/terraform-github-repo) — internal, supports `template_repo` + `managed_extra_files` +- ❌ Do not use SSH-based remote module sources (`git::ssh://`) — Census proxy blocks SSH host key exchange; use HTTPS +- ❌ Do not add `vpc_id` as a parameter to SC product templates — use `vpc_name` +- ❌ Do not write temp files or command output to `/tmp` — use `~/tmp` (i.e. `/home/a/arnol377/tmp`) instead +- ❌ Do not use the `terraform` command directly — always use the `tf` alias (e.g. `tf plan`, `tf apply`, `tf init`)