-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: rewrite copilot-instructions to reflect CodeBuild+Terraform arc…
…hitecture - Replace 'Lambda-Only Approach' and 'Do NOT suggest CodeBuild' sections - Document full buildspec.yml runtime environment (proxy, CA cert, TF binary from S3) - Add complete Key Resources table with CodeBuild projects and token sources - Add Important Runtime Notes section with Census-specific networking requirements - Update What NOT to Do section with correct guidance
- Loading branch information
Your Name
committed
Apr 7, 2026
1 parent
20f9681
commit 8503bc6
Showing
1 changed file
with
133 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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`) |