From 86f549b0fc5c4bc3f29d24463f2039f47a96dce0 Mon Sep 17 00:00:00 2001 From: Dave Arnold Date: Wed, 20 May 2026 14:29:23 -0400 Subject: [PATCH] docs: SC product registration via Terraform for_each, not manual steps --- ...eralized-terraform-product-architecture.md | 64 +++++++++++++++---- docs/template-management.md | 5 +- 2 files changed, 54 insertions(+), 15 deletions(-) diff --git a/docs/generalized-terraform-product-architecture.md b/docs/generalized-terraform-product-architecture.md index 4f8d663..aa13c04 100644 --- a/docs/generalized-terraform-product-architecture.md +++ b/docs/generalized-terraform-product-architecture.md @@ -259,15 +259,15 @@ auditable (every template repo change is a PR in the SCT-Engineering org). **Adding a new product type requires only creating a new template repo with a `handler.py`. No Lambda code changes, no Lambda redeployment, no registry entries.** -### 5. CloudFormation product template +### 5. CloudFormation product template + Terraform registration -Create a new `service-catalog/{product_type}-product-template.yaml`. The template -follows the same pattern as the EKS product template: +The CFN template for a product type lives in `service-catalog/{product_type}-product-template.yaml` +inside the `sc-lambda-ghactions` repo. It follows the same pattern as the existing EKS template: - Parameters for user-facing form fields - A single `Custom::TerraformRepo` resource -- Properties passed in `snake_case` to avoid the PascalCase normalizer issue -- `product_type` included as a static string property +- Properties in `snake_case` (avoids PascalCase normalizer edge cases) +- `product_type` as a static string property - `aws_account_id` and `aws_region` resolved via `!Sub` — not user-facing parameters ```yaml @@ -283,11 +283,48 @@ Properties: tier: !Ref Tier ``` -### 6. Census config YAML (portfolio registration) +**The template is never registered manually.** The `deploy/service_catalog.tf` workspace +manages all SC infrastructure — S3 upload, portfolio, product, provisioning artifact, +launch role, launch constraint, and principal associations — using `for_each` over a +`var.sc_products` map. This is the same proven pattern as `deploy_product/main.tf` in +`lambda-template-repo-generator`. + +Adding a new product type requires only two steps: + +1. Add an entry to `var.sc_products` in `deploy/terraform.tfvars`: + +```hcl +sc_products = { + ekscluster = { + name = "EKS Cluster Repository Creator" + description = "Creates an EKS cluster account repo from template-eks-cluster." + template = "service-catalog/eks-cluster-product-template.yaml" + version = "2.0.0" + } + s3bucket = { + name = "S3 Bucket Repository Creator" + description = "Creates an S3 bucket account repo from template-s3-bucket." + template = "service-catalog/s3-bucket-product-template.yaml" + version = "1.0.0" + } +} +``` + +2. Run `tf apply` in `deploy/` — Terraform creates (or updates) all SC resources for the new entry. + +No AWS Console clicks, no manual artifact uploads, no census pipeline PR required to +test a new product type in the dev/lab environment. + +### 6. Promotion to production via the census pipeline + +The `deploy/` workspace is the **development and testing path**. Once a new product type +has been validated end-to-end, it is promoted to production by adding the corresponding +entry to `terraform-service-catalog-census/templates/products/{product_type}/` and opening +a PR in `terraform-service-catalog-census`. The census pipeline applies this to all shared +accounts via the standard portfolio-sharing mechanism. -Add a new YAML file under `terraform-service-catalog-census/templates/products/{product_type}/` -to register the product in the SC portfolio. This follows the same structure as the -existing EKS product config. +The CFN template file (`service-catalog/{product_type}-product-template.yaml`) is the +single source of truth — both the `deploy/` workspace and the census pipeline read from it. --- @@ -302,10 +339,11 @@ onboard any new Terraform workload without Lambda or CodeBuild changes: - `tf-run.data` - `.sc-automation.yml.j2` (optional; Proposer writes a default if absent) **No files in the Lambda repository need to be created or modified.** -- [ ] Create `service-catalog/{product_type}-product-template.yaml` CFN template -- [ ] Add census config YAML and SC portfolio registration in `terraform-service-catalog-census` -- [ ] Test end-to-end via `scripts/test_service_catalog.py` with the new product type -- [ ] Confirm `.sc-automation.yml` is written correctly by the Proposer build +- [ ] Add `service-catalog/{product_type}-product-template.yaml` CFN template to `sc-lambda-ghactions` +- [ ] Add an entry to `var.sc_products` in `deploy/terraform.tfvars` and run `tf apply` in `deploy/` — + Terraform registers the SC portfolio, product, artifact, launch role, constraint, and principals +- [ ] Validate end-to-end in the dev/lab account via `scripts/test_service_catalog.py` +- [ ] Promote to production: add entry to `terraform-service-catalog-census/templates/products/{product_type}/` and open a PR --- diff --git a/docs/template-management.md b/docs/template-management.md index ddb8038..d52408a 100644 --- a/docs/template-management.md +++ b/docs/template-management.md @@ -308,5 +308,6 @@ Checklist when onboarding a new product type: - `tf-run.data` - `.sc-automation.yml.j2` (optional) **No files in the Lambda repository need to be created or modified.** -- [ ] Create a CFN product template in `service-catalog/{product_type}-product-template.yaml` -- [ ] Add the product to `terraform-service-catalog-census` (see [service-catalog-census-integration.md](service-catalog-census-integration.md)) +- [ ] Add `service-catalog/{product_type}-product-template.yaml` to `sc-lambda-ghactions` +- [ ] Add entry to `var.sc_products` in `deploy/terraform.tfvars` and run `tf apply` in `deploy/` +- [ ] Promote to production via `terraform-service-catalog-census` PR