OCM-00000 | docs: update ROSA HCP documentation to clarify module scope for AWS-only configurations

Author: amandahla

.cursor/rules/rosa-hcp-terraform.mdc

@@ -1,5 +1,5 @@
 ---
-description: ROSA HCP guardrails — architecture, providers, versions, security, variables
+description: ROSA HCP guardrails — architecture, module scope, providers, versions, security, variables
 alwaysApply: true
 ---
 
@@ -30,6 +30,22 @@ This repository implements **ROSA with Hosted Control Plane (HCP)** only. Do not
 - **AWS** resources and data sources must be supported by the **AWS** provider version range in **root** and that submodule’s `versions.tf` (same floor policy as **Provider & version constraints**).
 - Adding or bumping **`required_providers`** in a submodule must stay consistent across the **module tree** — root `versions.tf` must reflect minimum compatible versions for providers used anywhere in the tree.
 
+## Module scope (AWS-only vs core HCP)
+
+The tree includes **AWS-only** pieces (VPC, IAM, endpoints, etc.) that exist to run **ROSA HCP** in the customer account. Not every AWS pattern belongs in this repository.
+
+**In scope — expand or add AWS-only configuration when all of the following hold:**
+
+- **Reference-aligned:** The pattern is **standard for ROSA HCP**, part of the **reference architecture**, and **called out in official Red Hat documentation** (or in AWS documentation where Red Hat explicitly ties HCP to that AWS behavior).
+- **High misconfiguration risk:** Users are **likely to get it wrong** if they implement it themselves (availability, security, or cluster lifecycle impact).
+- **Sustainable:** It is **reasonable to test and support** (e.g. `terraform test`, examples, and docs) without unbounded optional surface area.
+
+**Out of scope — do not expand the module for:**
+
+- **Optional AWS** shapes that **vary widely by customer**, are **not** reference architecture, and are **not** documented in official Red Hat (or cited HCP-specific) docs. Prefer **examples**, documented patterns, or **user-owned** Terraform composed alongside this module.
+
+PRs that are **primarily AWS-only** should **link** the relevant official documentation so reviewers can confirm reference alignment.
+
 ## Security
 
 - Do not hardcode secrets or long-lived AWS keys in Terraform. Align with existing **`examples/`** and Red Hat guidance for STS, OIDC, and IRSA. Use **`sensitive`** where appropriate; avoid exposing secrets in outputs, state-adjacent logging, or ad-hoc debug prints.

.github/pull_request_template.md

@@ -76,6 +76,7 @@ For details, see: ./CONTRIBUTING.md
 Examples: variable rename/removal, output rename/removal, default value change, resource behavior changes, provider/version requirement changes. -->
 
 ## Developer Verification Checklist
+- [ ] **AWS-only changes:** If this PR is mainly **AWS-only** (no `rhcs` resources/variables), I linked **official Red Hat or cited ROSA HCP documentation** that supports reference alignment, or I explained why the change still belongs in-repo per **Module scope (AWS-only vs core HCP)** in [`.cursor/rules/rosa-hcp-terraform.mdc`](.cursor/rules/rosa-hcp-terraform.mdc).
 - [ ] I checked if this affects terraform-rhcs-rosa-classic and submitted (or already submitted) a companion PR when needed.
 - [ ] Commit subject/title follows `[JIRA-TICKET] | [TYPE]: <MESSAGE>`.
 - [ ] PR description clearly explains both **what** changed and **why**.

AGENTS.md

@@ -58,15 +58,20 @@ Useful skills for this codebase:
 - Breaking Changes: Do NOT change existing variable names or types without a migration plan (refactor-module skill).
 - HCP Specifics: Always verify if a feature is supported in HCP vs. Classic. If the `rhcs` resource type does not include `_hcp`, double-check the provider docs.
 
+## Module scope (AWS-only configuration)
+
+Not every AWS resource belongs in this repo. **When to add or expand AWS-only modules** vs leaving configuration to users is defined in [`.cursor/rules/rosa-hcp-terraform.mdc`](.cursor/rules/rosa-hcp-terraform.mdc) — section **Module scope (AWS-only vs core HCP)**. Favor **reference-documented**, **error-prone-if-DIY**, and **testable** patterns; defer **optional, customer-variable** AWS glue that official docs do not prescribe.
+
 ## Workflow Logic for Agents
 
 When asked to add a feature, the agent should follow this internal loop:
 
 1. Verify Provider Support: Check the provider schema/docs for the version range in root versions.tf.
 2. Check versions.tf: Does this require a provider bump? If yes, modify the root versions.tf first.
-3. Variable Standard: Add variables using the description / type / default order. Ensure descriptions match the upstream provider docs.
-4. Docs and tests: apply the required commands and verification steps from **`CONTRIBUTING.md`**.
-5. Security: follow **Security** above (canonical rules in `.cursor/rules` first, then the agent-oriented bullets).
+3. **Module scope:** For new or expanded **AWS-only** behavior, confirm it meets **Module scope (AWS-only vs core HCP)** in [`.cursor/rules/rosa-hcp-terraform.mdc`](.cursor/rules/rosa-hcp-terraform.mdc); prefer examples or user-owned Terraform when docs do not support in-repo ownership.
+4. Variable Standard: Add variables using the description / type / default order. Ensure descriptions match the upstream provider docs.
+5. Docs and tests: apply the required commands and verification steps from **`CONTRIBUTING.md`**.
+6. Security: follow **Security** above (canonical rules in `.cursor/rules` first, then the agent-oriented bullets).
 
 ## Testing Expectations
 

CONTRIBUTING.md

@@ -21,3 +21,4 @@ This repo is **ROSA HCP** only. The sibling **ROSA Classic** module is [`terrafo
 3. **Docs** — If you changed variables, outputs, modules, or root wiring: run `make verify-gen` (runs `terraform-docs` via [`scripts/terraform-docs.sh`](scripts/terraform-docs.sh), then [`scripts/verify-gen.sh`](scripts/verify-gen.sh) to ensure README inject blocks are committed).
 4. **Module tests** — If a submodule under `modules/<name>/tests/` has `*.tftest.hcl`, run `terraform init -backend=false && terraform test` from `modules/<name>/`.
 5. **Provider** — Treat [`terraform-redhat/rhcs`](https://github.com/terraform-redhat/terraform-provider-rhcs) as the source of truth: mirror its schemas in variables and docs. Add `validation` / `precondition` only to echo the provider’s required fields and allowed values (fail fast); do not duplicate or tighten rules the provider already enforces.
+6. **Module scope (AWS-only)** — If the change adds or expands **AWS-only** configuration (no `rhcs` surface), confirm it matches **Module scope (AWS-only vs core HCP)** in [`.cursor/rules/rosa-hcp-terraform.mdc`](.cursor/rules/rosa-hcp-terraform.mdc). In the PR, **link official Red Hat or cited ROSA HCP documentation** that supports shipping it in-repo, or explain why an exception is justified.