diff --git a/CHANGELOG.md b/CHANGELOG.md index e3842ca..ade3d48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ ### Added +- **`outputs.tf` in every generated environment** ([#9]). A generated repo built + infrastructure and then declined to say what it built: no cluster endpoint, no + database address, no subnet ids, so the only way to find them was + `terraform state show`. That is a workaround, not a workflow, and it does not + survive being put in a pipeline. Outputs are an explicit per-stack allowlist, + never a forwarding of everything the upstream modules expose, and **there is no + password output and no output that reaches one**: `terraform output` is not a + privileged operation, `-json` ignores `sensitive`, and CI logs are not private. + A test fails on any output whose name or value expression is password-shaped. + The generated README gains a "Consuming what it built" section with the + `aws eks update-kubeconfig` line. - **Stub stacks now say so, everywhere someone might look** ([#10]). Six of the nine advertised stacks emit a module reference and a name and nothing else. `terraform validate` accepts that, because every argument they omit defaults @@ -75,6 +86,7 @@ A generated `eks` + `rds` repository now plans cleanly: **64 resources to add, [#7]: https://github.com/ehtishammubarik/stackmason/issues/7 [#8]: https://github.com/ehtishammubarik/stackmason/issues/8 +[#9]: https://github.com/ehtishammubarik/stackmason/issues/9 [#10]: https://github.com/ehtishammubarik/stackmason/issues/10 [#11]: https://github.com/ehtishammubarik/stackmason/issues/11 [#12]: https://github.com/ehtishammubarik/stackmason/issues/12 diff --git a/ROADMAP.md b/ROADMAP.md index f8159fa..d686894 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -64,6 +64,7 @@ Shipped, tested, and on PyPI. | `suggest` on every sizing question | reasoning written to `DECISIONS.md` | | **Explicit provider region and `default_tags`** | region is never inherited from the ambient shell ([#15]) | | Generated repo is `terraform fmt` clean | so it passes the CI it ships with on its first commit | +| **`outputs.tf` per environment** | subnet ids, cluster endpoint, database address. No password output and none that reaches one ([#29]) | | A real `plan` verified | `eks` + `rds` plans 64 resources, 0 changes, 0 destroys | ## Next (0.2) @@ -81,7 +82,6 @@ matters more.** Each is self-contained and independently mergeable. | [Configure `redshift`](https://github.com/ehtishammubarik/stackmason/issues/25) | The most expensive stub to discover at apply time | | [Configure `observability`](https://github.com/ehtishammubarik/stackmason/issues/26) | Largest. Helm releases, not a module reference; needs providers no generated repo configures yet | | [Stub tracking issue](https://github.com/ehtishammubarik/stackmason/issues/10) | Closes when all six are done | -| [Generated environments have no outputs](https://github.com/ehtishammubarik/stackmason/issues/9) | Nothing downstream can consume the repo | | [Plan summary before writing](https://github.com/ehtishammubarik/stackmason/issues/1) | Cost and blast radius visible before a file is created | | [The interview never asks for a region](https://github.com/ehtishammubarik/stackmason/issues/14) | Needs a notion of questions belonging to no stack | @@ -146,3 +146,4 @@ touching what gets emitted. [#15]: https://github.com/ehtishammubarik/stackmason/pull/15 [#19]: https://github.com/ehtishammubarik/stackmason/pull/19 +[#29]: https://github.com/ehtishammubarik/stackmason/pull/29 diff --git a/stackmason/generate.py b/stackmason/generate.py index b761ab0..0e5d49e 100644 --- a/stackmason/generate.py +++ b/stackmason/generate.py @@ -378,6 +378,106 @@ def _module_block(sid: str, answers: dict, env: str) -> str: return "\n".join(lines) + "\n" +@dataclass(frozen=True, slots=True) +class Output: + """One value a generated environment publishes. + + Outputs are the seam between this repository and everything downstream: a + Helm values file, a deploy job, another configuration reading it through + `terraform_remote_state`. Without them the generated repo builds + infrastructure and then declines to say what it built. + """ + + name: str + value: str + description: str + sensitive: bool = False + + def render(self) -> str: + lines = [f'output "{self.name}" {{'] + lines.append(f" value = {self.value}") + lines.append(f' description = "{self.description}"') + if self.sensitive: + lines.append(" sensitive = true") + lines.append("}") + return "\n".join(lines) + "\n" + + +# What each stack publishes. An explicit allowlist, never a forwarding of +# everything upstream exposes. +# +# The distinction matters more than it looks. `terraform-aws-modules/rds` also +# exposes `db_instance_master_user_secret`, and a generator that forwarded +# outputs wholesale would be one upstream release away from publishing a +# credential it never meant to. `terraform output` is not privileged: anyone who +# can read the state can read every output, `-json` ignores `sensitive`, and CI +# logs are not private. So the rule is not "mark the secret sensitive", it is +# never create an output that reaches it. +STACK_OUTPUTS: dict[str, tuple[Output, ...]] = { + "vpc": ( + Output("vpc_id", "module.vpc.vpc_id", "VPC id, for anything that attaches to this network"), + Output( + "private_subnets", + "module.vpc.private_subnets", + "Private subnet ids. Where workloads belong", + ), + Output( + "public_subnets", + "module.vpc.public_subnets", + "Public subnet ids. Load balancers and NAT only", + ), + Output( + "database_subnets", + "module.vpc.database_subnets", + "Database subnet ids, used by the RDS subnet group", + ), + ), + "eks": ( + Output( + "cluster_name", "module.eks.cluster_name", "Cluster name, for aws eks update-kubeconfig" + ), + Output("cluster_endpoint", "module.eks.cluster_endpoint", "Kubernetes API endpoint"), + Output( + "cluster_certificate_authority_data", + "module.eks.cluster_certificate_authority_data", + "Cluster CA certificate. Not a secret, but a large blob that ruins a plan diff", + sensitive=True, + ), + ), + "rds": ( + Output( + "db_instance_address", + "module.rds.db_instance_address", + "Database hostname. The value an application config needs", + ), + Output("db_instance_port", "module.rds.db_instance_port", "Database port"), + ), +} + + +def _outputs_tf(stacks: list[str]) -> str: + """Outputs for the selected stacks, and nothing else. + + A stack that was not selected contributes nothing, so a generated repo + never references a module it does not have. + """ + header = ( + "# What this environment publishes.\n" + "#\n" + "# Deliberately short. These are the values something downstream actually\n" + "# consumes, not everything the upstream modules expose.\n" + "#\n" + "# There is no password output, and there is no output that reaches one.\n" + "# `terraform output` is not a privileged operation, `-json` ignores the\n" + "# sensitive flag, and CI logs are not private. Read the password from\n" + "# wherever you supplied it, never from here.\n" + ) + blocks = [o.render() for sid in stacks for o in STACK_OUTPUTS.get(sid, ())] + if not blocks: + return header + "\n# No stack in this environment publishes anything yet.\n" + return header + "\n" + "\n".join(blocks) + + def _locals(stacks: list[str], answers: dict) -> str: """Values referenced more than once, named once. @@ -456,6 +556,7 @@ def build_plan( plan.files[f"{base}/versions.tf"] = _versions_tf() plan.files[f"{base}/providers.tf"] = _providers_tf(project, env, region) plan.files[f"{base}/backend.tf"] = _backend_tf(env, project, region) + plan.files[f"{base}/outputs.tf"] = align_hcl(_outputs_tf(resolved)) plan.files[f"{base}/variables.tf"] = _variables_tf(variables) plan.files[f"{base}/terraform.tfvars.example"] = _tfvars_example(variables) @@ -652,6 +753,30 @@ def _readme(project: str, stacks: list[str], envs: list[str], answers: dict) -> else: secrets = "No stack in this repository requires a credential.\n" + readme_region = str(answers.get("aws_region") or DEFAULT_REGION) + consume_lines = [ + "```bash", + "terraform output # everything this environment publishes", + ] + if "eks" in stacks: + consume_lines += [ + "", + "# Point kubectl at the cluster this repository built:", + "aws eks update-kubeconfig \\", + " --name $(terraform output -raw cluster_name) \\", + f" --region {readme_region}", + ] + if "rds" in stacks: + consume_lines += [ + "", + "# Where the application connects. Never the password: that is not", + "# an output, deliberately. Read it from wherever you supplied it.", + "terraform output -raw db_instance_address", + "terraform output -raw db_instance_port", + ] + consume_lines.append("```") + consume = "\n".join(consume_lines) + return f"""# {project} Infrastructure for **{project}**, generated by @@ -681,6 +806,17 @@ def _readme(project: str, stacks: list[str], envs: list[str], answers: dict) -> `terraform.tfvars` is gitignored. It stays that way. +## Consuming what it built + +`outputs.tf` publishes the values something downstream needs. They are readable +after apply, and through `terraform_remote_state` from another configuration. + +{consume} + +There is no password output and no output that reaches one. `terraform output` +is not a privileged operation, `-json` ignores the `sensitive` flag, and CI logs +are not private. + ## Secrets No credential is committed anywhere in this repository, and none should be. diff --git a/tests/test_stackmason.py b/tests/test_stackmason.py index 6f5d312..a4d19d1 100644 --- a/tests/test_stackmason.py +++ b/tests/test_stackmason.py @@ -866,3 +866,111 @@ def test_roadmap_links_every_open_stub_stack(): assert f"Configure `{stack.id}`" in roadmap, ( f"{stack.id} is a stub with no roadmap row pointing at its issue" ) + + +# -------------------------------------------------------------------------- +# Generated outputs (issue #9) +# +# `terraform output` is not a privileged operation: anyone who can read the +# state can read every output, `-json` ignores `sensitive`, and CI logs are not +# private. So the rule is not "mark the secret sensitive", it is never create an +# output that reaches the password at all. +# -------------------------------------------------------------------------- + +# Substrings that must never appear in an output name or in what it references. +# Deliberately broad: a false positive costs one rename, a false negative +# publishes a credential. +SECRET_SHAPED = ( + "password", + "passwd", + "secret", + "master_user", + "credential", + "private_key", + "token", +) + + +def _outputs_tf(stacks: list[str], env: str = "dev") -> str: + answers = {**BASE, "engine": "postgres"} + plan = build_plan(Path("/x"), "acme", stacks, [env], answers) + return plan.files.get(f"environments/{env}/outputs.tf", "") + + +def _output_blocks(text: str) -> dict[str, str]: + """Map output name -> body, from generated HCL.""" + blocks: dict[str, str] = {} + for match in re.finditer(r'output\s+"([^"]+)"\s+\{(.*?)\n\}', text, re.S): + blocks[match.group(1)] = match.group(2) + return blocks + + +def test_every_environment_gets_an_outputs_file(): + assert _outputs_tf(["vpc"]).strip(), "no outputs.tf was generated" + + +def test_no_output_is_named_or_sourced_from_anything_password_shaped(): + """The load-bearing test for #9. + + Checks the name and the value expression. An output called `endpoint` that + reads `module.rds.db_instance_master_user_secret` is exactly as dangerous + as one called `password`, and only the second is caught by reading names. + """ + for stacks in (["vpc"], ["vpc", "eks"], ["vpc", "rds"], ["vpc", "eks", "rds"]): + blocks = _output_blocks(_outputs_tf(stacks)) + for name, body in blocks.items(): + # Name and value expression only. `description` is prose written for + # a human and may legitimately say "not a secret"; scanning it + # produces false positives whose only fix is writing a worse + # description. What can leak is what the output exposes. + value = next( + ( + ln.split("=", 1)[1].strip() + for ln in body.splitlines() + if ln.strip().startswith("value") + ), + "", + ) + haystack = f"{name} {value}".lower() + for needle in SECRET_SHAPED: + assert needle not in haystack, ( + f"output {name!r} for stacks {stacks} touches {needle!r}: value = {value!r}" + ) + + +def test_outputs_cover_only_the_stacks_that_were_selected(): + """A repo generated without RDS must not reference module.rds.""" + for stacks in (["vpc"], ["vpc", "eks"], ["vpc", "rds"]): + text = _outputs_tf(stacks) + for absent in {"vpc", "eks", "rds"} - set(stacks): + assert f"module.{absent}." not in text, ( + f"outputs.tf references module.{absent} but {absent} was not selected" + ) + + +@pytest.mark.parametrize( + ("stack", "expected"), + [ + ("vpc", ("vpc_id", "private_subnets", "public_subnets", "database_subnets")), + ("eks", ("cluster_name", "cluster_endpoint", "cluster_certificate_authority_data")), + ("rds", ("db_instance_address", "db_instance_port")), + ], +) +def test_each_stack_contributes_the_outputs_a_consumer_needs(stack, expected): + stacks = ["vpc"] if stack == "vpc" else ["vpc", stack] + blocks = _output_blocks(_outputs_tf(stacks)) + for name in expected: + assert name in blocks, f"{stack} selected but output {name!r} missing" + + +def test_the_cluster_ca_certificate_is_marked_sensitive(): + """Not a secret, but it is a large base64 blob that ruins a plan diff and + has no business being echoed by default.""" + blocks = _output_blocks(_outputs_tf(["vpc", "eks"])) + # Alignment-insensitive: align_hcl pads `=` to the longest key in the run, + # so the exact spacing shifts whenever a neighbouring key changes length. + assert re.search(r"^\s+sensitive\s+= true$", blocks["cluster_certificate_authority_data"], re.M) + + +def test_outputs_file_is_already_fmt_clean(): + assert align_hcl(_outputs_tf(["vpc", "eks", "rds"])) == _outputs_tf(["vpc", "eks", "rds"])