132 lines
6.7 KiB
Markdown
132 lines
6.7 KiB
Markdown
---
|
|
name: requirements-chain
|
|
description: >-
|
|
Defines the data files that carry requirements through to code and validation:
|
|
requirements, components, products, recommendations, the Target architecture
|
|
graph, the implementation map and the verdicts. Use when producing or checking
|
|
any Deliverable of a solution-architecture Execution, to write its data file
|
|
in the right format and keep every id traceable.
|
|
metadata:
|
|
scope: every Deliverable
|
|
---
|
|
|
|
# Requirements chain
|
|
|
|
Every requirement must be traceable, by id, to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. Each Deliverable attaches one data file that carries its part of that chain. A submission is refused when a link is missing, and the refusal names it.
|
|
|
|
Ids are short and stable: reuse an id exactly as the earlier Deliverable wrote it, and never renumber.
|
|
|
|
## The files
|
|
|
|
### `requirements.json` (requirements)
|
|
|
|
A list. Number functional requirements `FR-1`, `FR-2` and non-functional ones `NFR-1`, `NFR-2`.
|
|
|
|
```json
|
|
[
|
|
{"id": "FR-1", "kind": "functional", "text": "Accept signed webhooks over HTTPS."},
|
|
{"id": "NFR-1", "kind": "non_functional", "text": "Raw events are retained for 30 days."}
|
|
]
|
|
```
|
|
|
|
`kind` is `functional` or `non_functional`. Write one requirement per entry, so each can be checked on its own.
|
|
|
|
### `components.json` (technical decomposition)
|
|
|
|
A list of components and the requirement ids each serves. Every functional requirement must be served by at least one component.
|
|
|
|
```json
|
|
[{"id": "C-1", "name": "Ingest endpoint", "requirements": ["FR-1"]}]
|
|
```
|
|
|
|
### `products.json` (product selection)
|
|
|
|
One entry per component, naming the product selected for it.
|
|
|
|
```json
|
|
[{"component": "C-1", "product": "Cloud Run"}]
|
|
```
|
|
|
|
### `recommendations.json` (design recommendations)
|
|
|
|
A list. Each recommendation names its pillar and the components it applies to; use an empty list for one that applies to the whole workload.
|
|
|
|
```json
|
|
[{"id": "DR-1", "pillar": "security", "text": "Encrypt the topic with a customer-managed key.", "components": ["C-2"]}]
|
|
```
|
|
|
|
Write one configurable decision per recommendation. "Harden the service" cannot become a Check; "disable public ingress on the worker service" can.
|
|
|
|
### `target-architecture.json` (Target architecture)
|
|
|
|
```json
|
|
{
|
|
"elements": [
|
|
{"id": "E-1", "name": "Ingest service", "component": "C-1", "product": "Cloud Run", "resource_type": "google_cloud_run_v2_service"},
|
|
{"id": "E-2", "name": "Ingest identity", "product": "IAM", "resource_type": "google_service_account"}
|
|
],
|
|
"relationships": [
|
|
{"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"}
|
|
],
|
|
"checks": [
|
|
{"id": "K-1", "applies_to": "E-1", "statement": "ingress is INGRESS_TRAFFIC_ALL and roles/run.invoker is granted to allUsers", "source": "FR-1"},
|
|
{"id": "K-2", "applies_to": "E-2", "statement": "the account is attached to E-1 only", "source": "DR-3"}
|
|
],
|
|
"not_applicable": [
|
|
{"recommendation": "DR-9", "reason": "Single region by requirement NFR-2."}
|
|
]
|
|
}
|
|
```
|
|
|
|
- **Elements.** One per resource to be created. `component` is the component it realises; leave it out for a supporting Element such as an identity, a key or a network. `product` for a component's Element is exactly the product selected for that component.
|
|
- **Relationships.** `from` and `to` are Element ids. `kind` says what the connection is: calls, publishes to, reads from, runs as, is granted access to.
|
|
- **Checks.** `applies_to` is an Element or Relationship id. `source` is the requirement or recommendation id the Check comes from. Every Element has at least one Check.
|
|
- **Completeness.** Every component has an Element. Every non-functional requirement and every recommendation is the `source` of at least one Check, unless the recommendation is listed under `not_applicable` with a reason. Every selected product appears on its component's Element.
|
|
|
|
#### Writing a Check
|
|
|
|
A Check is a statement that is true or false of the infrastructure code. Name the argument and the value.
|
|
|
|
- Verifiable: "`kms_key_name` is set on the topic", "`min_instance_count` is at least 2", "the subscription has a `dead_letter_policy` pointing at E-6".
|
|
- Not verifiable: "the service is secure", "follows least privilege", "scales well".
|
|
|
|
Split a broad recommendation into several Checks, one per setting. A Check that the validator cannot verify from the code is sent back to you.
|
|
|
|
A Check must name a setting its Element's resource type really has. Two similar resource types often differ: a setting of a long-running service may not exist on a batch job. A Check on a setting the resource type lacks is sent back to you.
|
|
|
|
The tables of Elements, Relationships and Checks, and the diagram, are written from this file when you submit. Write the graph once, here.
|
|
|
|
### `implementation.json` (deployment guidance)
|
|
|
|
One entry per Check in the Target architecture, saying where the code satisfies it. `file` is an attached file; `address` is the resource address and argument.
|
|
|
|
```json
|
|
[
|
|
{"check": "K-1", "file": "terraform/main.tf", "address": "google_cloud_run_v2_service.ingest.ingress"},
|
|
{"check": "K-7", "unimplementable": "google_cloud_run_v2_job has no startup_cpu_boost argument; it exists only on a service."}
|
|
]
|
|
```
|
|
|
|
When a Check names a setting its resource type does not have, give it an `unimplementable` entry in place of `file` and `address`, saying what the resource type lacks. Write no code for it. The Target architecture is revised before anything is validated.
|
|
|
|
Implement every Element, Relationship and Check, and nothing the Target architecture does not ask for. When you believe the Target architecture is wrong or incomplete, say so with `needs_input`; do not quietly build something else.
|
|
|
|
### `verdicts.json` (validation results)
|
|
|
|
```json
|
|
{
|
|
"dry_run": {"verdict": "pass", "evidence": "terraform validate: Success! The configuration is valid."},
|
|
"checks": [
|
|
{"check": "K-1", "verdict": "pass", "evidence": "main.tf: ingress = \"INGRESS_TRAFFIC_ALL\"; google_cloud_run_v2_service_iam_member.public"},
|
|
{"check": "K-2", "verdict": "fail", "evidence": "google_service_account.ingest is also attached to the worker service"}
|
|
],
|
|
"proposed_additions": [
|
|
{"statement": "the bucket has a retention_policy of 30 days", "applies_to": "E-5", "reason": "NFR-1 has no Check on retention"}
|
|
]
|
|
}
|
|
```
|
|
|
|
- Give every Check exactly one verdict: `pass`, `fail` or `not_verifiable`, with the evidence you read in the code.
|
|
- `dry_run.verdict` is `pass`, `fail`, or `not_run` when the tool could not run.
|
|
- Judge the code against the Checks and nothing else. Something the Target architecture lacks is a `proposed_additions` entry, with the requirement or recommendation id it serves in `reason`. It is never a failed Check.
|