Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 |

Expand Down Expand Up @@ -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
136 changes: 136 additions & 0 deletions stackmason/generate.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
108 changes: 108 additions & 0 deletions tests/test_stackmason.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"])
Loading