feat(P39): refresh design docs + parameterize adapter (P1-1)
---ci--- project: acdl phase: 39 milestone: v1.9 status: execute ---/ci--- Phase 39 — design-doc-refresh-and-p1-1-parameterization: Design docs (REQ-100, REQ-101): - hitl_matrix_design.md: 'dev-only spike'/'v1.2 wires the gates' framing replaced with v1.9 wired-gates reality; 8-concern matrix marked implemented (offline-testable subset + signed evidence artifacts, D-084); v1.9 wiring section cross-references hitl_gates.py + attestation_matrix.py; approver_dr noted. - audit_ledger_design.md: outbox marked shipped+production since v1.8; S3 Object Lock + JWS + async worker + DLQ + daily checkpoints clearly labeled 'Deferred to a future milestone (D-083)'; RPO/RTO table updated; approver fields note v1.9 hitl_gates.attest. P1-1 adapter parameterization (REQ-102, D-085): - ecs-service interface.json: desired_count (default 1), launch_type (FARGATE), family (app) inputs added. - alb interface.json: load_balancer_type (application), target_type (ip). - adapter.py: hardcoded defaults replaced with inputs.get(<name>, <default>); hardcoded 'acdl-microservice-rt'/'acdl-microservice-igw' Name tags derive from the VPC name input. - contract_resolver.py: child_input_map routes wires to the sub-resource that declares the input (desired_count → aws:ecs:service, family → aws:ecs:task_definition, target_type → targetgroup, etc.). - microservice composition.json: wires added for the new inputs. Tests: +21 (test_p1_1_adapter_parameterization.py, test_design_docs_current.py). 371 passed; run_ci.sh green; run_platform.sh --check-only green; v1.1 S3 regression preserved.
This commit is contained in:
Jon Chery
@@ -0,0 +1,247 @@
|
||||
# How the Platform Works
|
||||
|
||||
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
||||
> **Length:** ~15 minutes · 14 slides
|
||||
> **Purpose:** Sell the platform's value to tech leadership — zero-trust, security, observability, auditability, and the shift from "operators guess" to "the platform computes safety."
|
||||
> **Maturity framing:** "Available today" = shipped and verified. "Planned" = on the roadmap, not yet shipped.
|
||||
|
||||
---
|
||||
|
||||
## Slide 1 — The Problem We Solve
|
||||
|
||||
Software delivery scales with the **coordination surface around it**, not the engineering inside it. Most teams can write code; far fewer get the infrastructure right.
|
||||
|
||||
Two frictions slow every team down:
|
||||
|
||||
- **Cognitive load** — authoring the infrastructure that runs a service correctly. The long tail of well-meaning services that are difficult to deploy, inconsistent in security and observability posture.
|
||||
- **Operational work** — moving a merged change from "merged" to "running in production with policy, observability, and security enforced." Manual work that **scales with the system, not with the change.**
|
||||
|
||||
> **Speaker notes:** Open with the cost of the status quo. Every team that stands up its own pipeline, its own Terraform, its own review checklist is paying a tax that doesn't differentiate the business. The platform absorbs both frictions — that is the value proposition in one sentence.
|
||||
|
||||
---
|
||||
|
||||
## Slide 2 — The North Star
|
||||
|
||||
> Consumers **declare intent**; the platform delivers **safe production deployment** through an agentic stack — automatically, safely, and with a complete audit trail.
|
||||
|
||||
What success looks like:
|
||||
|
||||
- A merged change progresses through lower environments **end-to-end without a platform engineer joining a thread, approving a ticket, or manually triggering a stage.**
|
||||
- A **non-technical consumer** ships a production deployment by declaring intent — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
- Every production change is **traceable to a human attestation and an immutable evidence stream.**
|
||||
|
||||
> **Speaker notes:** This is the litmus test. If a platform engineer still has to touch a ticket for a dev→qa promotion, we haven't delivered the vision. The two consumer surfaces (technical developer + citizen developer) are covered in the companion deck. Here we focus on *how* the platform makes the North Star real.
|
||||
|
||||
---
|
||||
|
||||
## Slide 3 — The Contract-Driven Model
|
||||
|
||||
One small YAML file is all a consumer writes. The platform owns everything else.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Consumer<br/>writes a contract"] --> B["Platform resolves,<br/>compiles, checks,<br/>deploys, records"]
|
||||
B --> C["Resources running in AWS<br/>+ tamper-evident evidence"]
|
||||
```
|
||||
|
||||
The contract names three things:
|
||||
|
||||
- **Which module** — a catalog of pre-built, security-reviewed building blocks (a static site, a microservice, a database, and more).
|
||||
- **Which environment** — `dev`, `qa`, `prod`, or `dr`. The platform raises the safety bar automatically as the environment gets more sensitive.
|
||||
- **Which inputs** — the handful of values that vary per deployment (a bucket name, a container image, a port).
|
||||
|
||||
The consumer does **not** write infrastructure modules, workflow logic, or adapter code. They declare intent; the platform reconciles, provisions, and progresses.
|
||||
|
||||
> **Speaker notes:** Emphasize the asymmetry. The consumer's surface is intentionally tiny — a contract that fits on one screen. The platform's surface is large and opinionated. That asymmetry is what makes "declare intent, not execute operations" concrete.
|
||||
|
||||
---
|
||||
|
||||
## Slide 4 — The End-to-End Flow
|
||||
|
||||
Every deployment runs the same stages, in the same order, with the same checks — no team-specific pipelines, no tribal runbooks.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Consumer contract<br/>(module + environment + inputs)"] --> B["Validate contract<br/>against the schema"]
|
||||
B --> C["Resolve to a target stack<br/>(expand the module's pattern)"]
|
||||
C --> D["Security checks<br/>(before any infra is created)"]
|
||||
D --> E["Infrastructure plan<br/>(platform compiles the stack)"]
|
||||
E --> F["Policy checks<br/>(normalized results)"]
|
||||
F --> G["Confidence signal<br/>(6 inputs → score + band)"]
|
||||
G --> H["Evidence event<br/>(hash-chained, tamper-evident)"]
|
||||
H --> I["Infrastructure apply<br/>(dev only — higher envs hold for attestation)"]
|
||||
```
|
||||
|
||||
Two properties matter to leadership:
|
||||
|
||||
- **Security and policy checks run *before* any infrastructure is created** — not after the fact, not as a post-deployment audit.
|
||||
- **Every stage produces a record** that feeds the confidence signal and the evidence stream. There is no "unchecked" path.
|
||||
|
||||
> **Speaker notes:** Walk left to right once. Don't dwell on internals — the point is that the flow is fixed, opinionated, and identical for every consumer. The two leadership-relevant beats are (1) checks before creation, (2) every stage is evidenced. The confidence signal (Slide 6) is where the "safety is computed" story lands.
|
||||
|
||||
---
|
||||
|
||||
## Slide 5 — Zero-Trust by Default
|
||||
|
||||
Consumer repositories hold **no long-lived cloud credentials.** Ever.
|
||||
|
||||
- **Authentication** is **OIDC federation** between the platform runners and the cloud provider. Each job mints a short-lived token; no credential is stored in the consumer repo or in a runner secret. *(Available today on GitHub Actions runners; planned for all platform runners.)*
|
||||
- **Authorization** is **attribute-based (ABAC), not role-based.** Two attribute classes scope every action:
|
||||
- **Repository identity** — the role's trust policy binds to the exact consumer repo + branch that invoked the workflow.
|
||||
- **Resource-creation attributes** — every resource is tagged with `acdl:owner=<consumer-repo>` and `acdl:contract=<contract-id>`. The session policy grants view/update/delete **only on resources whose tags match the calling repo.**
|
||||
|
||||
**The effect:** a consumer's pipeline can only touch the resources it created. Blast radius is contained to that consumer's own stack instances. One consumer can never touch another's resources, and the consumer cannot escape its own scope.
|
||||
|
||||
> **Speaker notes:** This is the slide for the Head of Cloud/Security. The key phrase is "blast radius contained to the consumer's own stack." Contrast with the common failure mode of shared CI roles that can touch any account resource. The static-key override exists for edge cases but is rotated daily on platform runners; it is never the default.
|
||||
|
||||
---
|
||||
|
||||
## Slide 6 — Safety is Computed, Not Assumed
|
||||
|
||||
Every delivery action produces a **measurable, explainable confidence signal** — the platform's certified answer to "is this safe to proceed?"
|
||||
|
||||
- **Six weighted inputs:** policy conformance, validation, freshness, source provenance, history, and non-functional requirements (NFRs).
|
||||
- **Per-environment thresholds** that rise with sensitivity:
|
||||
|
||||
| Environment | Threshold | Who must attest |
|
||||
|---|---|---|
|
||||
| dev | ≥ 0.50 | No one — fully autonomous |
|
||||
| qa | ≥ 0.75 | QA |
|
||||
| prod | ≥ 0.90 | SRE |
|
||||
| dr | ≥ 0.95 | SRE + a disaster-recovery drill reference |
|
||||
|
||||
- **A single critical policy finding hard-blocks the deployment**, regardless of every other input. Critical findings are not averaged away.
|
||||
- **When the platform halts, it gives a measured reason** — a policy violation, an insufficient signal, a missing attestation — never an opaque, manual-debugging exercise.
|
||||
|
||||
> **Speaker notes:** This is the bet that separates this platform from "yet another CI/CD tool." Reliance on operator instinct or tenure is not a substitute. The signal is auditable; the thresholds are tunable by Infra & Ops + SRE jointly, and any override is itself a confidence-event in the audit stream. Leadership cares about this because it makes promotion decisions *reviewable*.
|
||||
|
||||
---
|
||||
|
||||
## Slide 7 — Policy & Security Enforcement
|
||||
|
||||
Checks run on **every** deployment, normalized to a single schema regardless of which engine produced them.
|
||||
|
||||
- **Infrastructure-as-code policy** (Checkov) — secrets in plaintext, public ingress, IAM wildcards, KMS key references, **required tagging standards** (`acdl:owner`, `acdl:contract`, `acdl:environment`, `acdl:cost-center`).
|
||||
- **Cloud security posture** (Wiz adapter) — translates cloud security findings into the same normalized record. *(Adapter available today; activates when a Wiz tenant is configured.)*
|
||||
- **Kubernetes-native policy** (Kyverno adapter) — ready for the GitOps reconciler roadmap item. *(Adapter available today; inactive for Terraform-only stacks.)*
|
||||
|
||||
Every check produces a record with **severity, rule ID, pass/fail status, and human-readable message** — consumed uniformly by the confidence signal. No engine-specific escapes.
|
||||
|
||||
> **Speaker notes:** The selling point is *normalization*. We can add a new security tool without changing the confidence model or the evidence stream. For the Head of Security: tagging standards are enforced, not advisory — a missing `acdl:owner` tag fails the check, not a warning.
|
||||
|
||||
---
|
||||
|
||||
## Slide 8 — Secure by Default
|
||||
|
||||
Security defaults that **do not require a team to opt in.**
|
||||
|
||||
- **Encryption on every resource** — at-rest encryption is on by default for every primitive (S3, RDS, ECR, ECS, and more). *(Available today.)*
|
||||
- **Per-stack customer-managed keys (CMKs)** — one key per deployment, 90-day rotation at creation, **no shared keys across stacks.** *(Available today.)*
|
||||
- **Managed-key fallback with a loud warning** — standalone primitives fall back to cloud-managed keys only when no CMK is provided, and the platform warns explicitly. Silent use of cloud-managed keys is a security gap we refuse to hide. *(Available today.)*
|
||||
- **Deletion protection on by default** — every resource has `prevent_destroy` on unless a consumer explicitly disables it via a documented feature flag. *(Available today.)*
|
||||
- **Safe decommission** — a 2-step pipeline (disable protection → zero counts → destroy) with **two SRE human-attestation gates** and a **change-request validated against the platform CMDB** before any destructive action. *(Available today.)* Encryption keys enter a grace window (default 30 days) so encrypted data remains recoverable during decommission.
|
||||
|
||||
> **Speaker notes:** The phrase to land is "secure by default, not secure by effort." The decommission flow is the counter-argument to "deletion protection makes cleanup impossible" — it's a deliberate, gated, two-approval path, not a lock with no key.
|
||||
|
||||
---
|
||||
|
||||
## Slide 9 — Immutable Audit & Evidence
|
||||
|
||||
Version control is a **coordination tool, not an evidentiary fortress.** True compliance requires an immutable, externally-stored ledger.
|
||||
|
||||
- **Every deployment writes a hash-chained evidence event** — each event links to the previous via a cryptographic hash. Tampering breaks the chain. *(Available today. the DynamoDB outbox.)*
|
||||
- **Tiered storage design:** cold, tamper-proof source of truth (S3 Object Lock, compliance mode, 7-year retention) + a hot query index for fast lookup. *(Outbox shipped; S3 Object Lock + JWS detached signatures are planned regulatory-ledger build-out.)*
|
||||
- **RPO = 0** — the evidence write is synchronous; a deployment is not acknowledged until the evidence event is durably recorded.
|
||||
- **Every production change is traceable to a human attestation** — the QA and prod approver identities are the only durable record outside the forge's audit log, stored in the outbox keyed by contract.
|
||||
|
||||
> **Speaker notes:** This is the slide for the Head of Infrastructure and anyone who has been through an audit. "The audit trail is a byproduct of deployment, not a project." Note honestly that the full regulatory ledger (S3 Object Lock, JWS signatures, daily checkpoints) is planned; what ships today is the outbox + hash chain that makes every event tamper-evident and queryable.
|
||||
|
||||
---
|
||||
|
||||
## Slide 10 — Human-in-the-Loop Where It Matters
|
||||
|
||||
Autonomy and accountability are **not in tension** — they are applied at different environments.
|
||||
|
||||
- **Dev is fully autonomous.** No human gate. The confidence signal (≥ 0.50) is the only gate. Queue-based handoffs are eliminated from lower environments.
|
||||
- **qa, prod, and dr require deliberate human attestation** — not rubber stamps, but policy-mandated acts of accountability via protected deployment approvals.
|
||||
- **Separation of duties is enforced** *(design shipped; wiring for qa/prod/dr is planned)* — the person who approved the qa promotion **cannot** be the person who approves the prod promotion. The platform reads both identities from the outbox and **blocks** on a match, emitting a `SEPARATION_OF_DUTIES_VIOLATION` and routing a halt artifact to SRE on-call.
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit. Rejection extends the audit chain; it does not tear it up.
|
||||
|
||||
> **Speaker notes:** The "Lower environments autonomous, higher environments attested" tenet is the resolution to the classic "move fast vs. be safe" false dichotomy. Be honest: the *mechanism* (CODEOWNERS routing, identity-distinctness check, the 8-concern attestation matrix) is designed and the dev path is wired; the qa/prod/dr wiring is on the roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Slide 11 — Observability Built In
|
||||
|
||||
Monitoring is **a platform default, not a per-team project.**
|
||||
|
||||
- **Uptime monitoring deployed automatically with every stack** — a dedicated monitoring instance (Uptime-kuma on ECS Fargate) is provisioned after any module deploy, in a separate state, with a feature flag to disable. *(Available today.)*
|
||||
- **Monitored endpoints passed from the deployment's own outputs** — the platform constructs a synthetic monitoring contract from what was just deployed. No manual endpoint registration.
|
||||
- **Alert channels:** Microsoft Teams webhook, email, SMS, and GitHub issues. *(Available today.)*
|
||||
- **The uptime URL is published to the developer** via a PR comment — they don't hunt for it.
|
||||
- **Roadmap:** deeper observability bootstrap (dashboards, runbooks, on-call bindings) as first-class contract fields for prod/dr.
|
||||
|
||||
> **Speaker notes:** The Head of DevOps cares about this. The framing: "you don't deploy a service and *then* remember to set up monitoring — the platform does it as part of the deploy." The feature flag means teams with existing monitoring (e.g. Datadog) can opt out cleanly.
|
||||
|
||||
---
|
||||
|
||||
## Slide 12 — Platform-Managed Environments
|
||||
|
||||
A consumer provides **no AWS account, no VPC, no subnet, no state backend, no runner key.** The platform owns the blast radius.
|
||||
|
||||
A named environment is a platform-owned bundle of:
|
||||
|
||||
- An AWS account (or a scoped partition of one).
|
||||
- A network (VPC + subnets).
|
||||
- A state backend (S3 + DynamoDB for infrastructure state + locking).
|
||||
- An IAM role surfaced to the consumer via ABAC, scoped to the consumer's repository identity and resource tags.
|
||||
|
||||
The consumer selects an environment **by name** in their contract (`environment: dev`). The platform resolves the name to the underlying account/network/state/role at run time. **The consumer never sees the raw credentials.**
|
||||
|
||||
**Friendly onboarding:** the first run detects no environment and emits a guided prompt (not an opaque failure) telling the consumer what the platform will provision and how to request it. *(Available today.)* **Self-service environment provisioning is planned.**
|
||||
|
||||
> **Speaker notes:** For the Head of Cloud: this is the governance story. The platform team owns the accounts, the network design, the state hygiene. Consumers can't drift into misconfigured state backends or over-permissioned roles because they never touch them. The onboarding prompt matters — first impressions of a platform are made when it fails for the first time.
|
||||
|
||||
---
|
||||
|
||||
## Slide 13 — Portability & Future-Proofing
|
||||
|
||||
The platform is **opinionated, but not painted into a corner.**
|
||||
|
||||
- **Substrate-agnostic core.** The contract, the resolved stack, the policy results, the confidence signal, and the evidence stream are all defined *without reference to any specific infrastructure tool.* Today there is one adapter (Terraform). *(OpenTofu, Pulumi, Kubernetes CRDs are future adapters — no architectural change required.)*
|
||||
- **Forge-agnostic contract ingestion.** The platform Lambda reads a configurable API base for GitHub or Gitea. *(Available today.)*
|
||||
- **Portable contracts.** The contract schema, the confidence signal, and the audit stream are substrate- and forge-agnostic. A second forge (e.g. GitLab) needs a forge adapter + a workflow-template translator — **no change to the modules, the contract standard, the confidence model, or the audit stream.**
|
||||
- **Pattern recognition compounds value over time.** As the platform observes recurring contract patterns, it can synthesize and offer reusable modules. *(Future capability, not a current commitment — but the design allows it.)*
|
||||
|
||||
> **Speaker notes:** This is the "we won't have to rewrite this in two years" slide. The bet is that the substrate (Terraform today) will change, but the contract + confidence + audit model won't. Leadership should hear: the investment is in the abstraction, not the tool.
|
||||
|
||||
---
|
||||
|
||||
## Slide 14 — Roadmap: Honest Shipped vs. Planned
|
||||
|
||||
**Available today:**
|
||||
|
||||
- Contract-driven deploys with a versioned reusable workflow.
|
||||
- Module catalog (primitives + modules) with validated examples.
|
||||
- Zero-trust OIDC + ABAC on GitHub Actions runners.
|
||||
- Security + policy checks before infra creation (Checkov; Wiz + Kyverno adapters ready).
|
||||
- Confidence signal (6 inputs, per-env thresholds) gating promotion.
|
||||
- Hash-chained, tamper-evident evidence outbox (RPO = 0).
|
||||
- Encryption by default + per-stack customer-managed keys.
|
||||
- Deletion protection by default + safe decommission with SRE gates + CMDB validation.
|
||||
- Uptime monitoring deployed automatically with every stack.
|
||||
- Platform-managed environments + friendly onboarding.
|
||||
- Local reproducibility (`run_ci.sh` mirrors the CI pipeline).
|
||||
- Forge-agnostic contract ingestion (GitHub + Gitea).
|
||||
|
||||
**Planned (on the roadmap, not yet shipped):**
|
||||
|
||||
- Real OIDC federation on all platform runners (Gitea Actions OIDC pending an upstream merge).
|
||||
- HITL wiring for qa / prod / dr environments (design shipped; wiring is next).
|
||||
- Full regulatory ledger: S3 Object Lock (7-yr compliance mode) + JWS detached signatures + daily checkpoints.
|
||||
- Compliance milestone: per-module extension points for GDPR, SOX, SOC2, HIPAA, DORA.
|
||||
- Environment self-service (a consumer-facing flow to request and provision a new environment).
|
||||
- Dynamic module creation from a contract (the agentic "citizen developer" composition mechanism).
|
||||
- Additional substrate adapters (OpenTofu, Pulumi, Kubernetes CRDs).
|
||||
|
||||
> **Speaker notes:** Close on honesty. The platform delivers real, verifiable value today — and the roadmap is concrete, not aspirational hand-waving. Invite questions on any "planned" item; each has a defined milestone and a clear reason it isn't shipped yet (usually an upstream dependency, not an engineering gap).
|
||||
@@ -0,0 +1,288 @@
|
||||
# The Developer Experience
|
||||
|
||||
> **Audience:** Senior Leadership, CTO, Head of Cloud, Head of Infrastructure, Head of DevOps
|
||||
> **Length:** ~15 minutes · 14 slides
|
||||
> **Purpose:** Sell the developer experience and the citizen developer experience to tech leadership — velocity without sacrificing safety, and security/observability/compliance as platform defaults rather than per-team effort.
|
||||
> **Maturity framing:** "Available today" = shipped and verified. "Planned" = on the roadmap, not yet shipped.
|
||||
|
||||
---
|
||||
|
||||
## Slide 1 — Two Consumer Surfaces, One Platform
|
||||
|
||||
The platform serves **two kinds of consumer** through two coordinated interfaces — but both converge on the **same contract, the same policy envelope, and the same evidence stream.**
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Technical developer"] --> C["Contract YAML"]
|
||||
B["Citizen developer<br/>(non-technical)"] --> D["Declares intent in<br/>natural language"]
|
||||
D --> E["Agent produces<br/>the contract"]
|
||||
C --> F["Same platform:<br/>resolve → check → plan → policy<br/>→ confidence → evidence → apply"]
|
||||
E --> F
|
||||
F --> G["Same safety guarantees,<br/>same audit trail"]
|
||||
```
|
||||
|
||||
- **Technical developer** — owns app code + a contract + a thin CI definition. Uses the full module catalog and inputs.
|
||||
- **Citizen developer** — declares intent in plain language; an agent produces a contract that passes the **same** safety envelope as a senior engineer's.
|
||||
|
||||
The platform is **opinionated in what it accepts, regardless of who is declaring.** There is no "citizen developer mode" with weaker checks.
|
||||
|
||||
> **Speaker notes:** This is the thesis of the deck. The two surfaces are *parallel*, not a progression — a citizen developer doesn't "graduate" to the developer surface. Both produce a contract; both get the same treatment. The leadership takeaway: we expand who can ship safely without lowering the bar.
|
||||
|
||||
---
|
||||
|
||||
## Slide 2 — What a Developer Actually Does
|
||||
|
||||
Three things. That is the entire consumer-side surface.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["1. App code<br/>(top level of the repo)"] --> D["Push to main"]
|
||||
B["2. Contract<br/>(.acdl/contract.yaml)"] --> D
|
||||
C["3. CI definition<br/>(.github/workflows/deploy.yml<br/>— one 'uses:' line)"] --> D
|
||||
D --> E["Platform does the rest"]
|
||||
```
|
||||
|
||||
The developer does **not**:
|
||||
|
||||
- Write infrastructure modules.
|
||||
- Author workflow YAML beyond the one-line `uses:` wrapper.
|
||||
- Clone the platform repo.
|
||||
- Hold cloud credentials.
|
||||
- Maintain a state backend, a VPC, or a runner.
|
||||
|
||||
> **Speaker notes:** Hold this slide. The audience should sit with how small the consumer surface is. Every item in the "does not" list is a category of toil the platform removes. For the Head of DevOps: this is the lever for throughput — the bottleneck moves off the platform team's ticket queue.
|
||||
|
||||
---
|
||||
|
||||
## Slide 3 — The Citizen Developer Experience
|
||||
|
||||
A non-technical consumer ships a production deployment **by declaring intent** — without authoring a workflow, a configuration file, or an infrastructure module.
|
||||
|
||||
- The consumer opens an issue describing what they need (e.g. "a web API for the pricing service").
|
||||
- An agent maps the intent to a contract referencing a module from the **reviewed skill catalog.**
|
||||
- The contract enters the **same pipeline** and must clear the **same confidence gate** before promotion.
|
||||
|
||||
**Guardrails that make this safe:**
|
||||
|
||||
- Skills are **versioned, signed, and reviewed for sensitive data before release** (Infra & Ops owns the review — it is the mandatory release gate).
|
||||
- Agents are **stateless** — all state lives in the platform. The platform does not run the skill blindly; it trusts and **always verifies** on the platform side.
|
||||
- The agent's trace and submission confidence are captured in the contract (`profile: agentic`), so a reviewer can see *how* the contract was produced.
|
||||
- **Initial skill catalog:** web API, worker, scheduled job, static asset, basic observability bootstrap. *(Catalog is planned; the agentic surface is on the roadmap.)*
|
||||
|
||||
> **Speaker notes:** Be honest about maturity: the *mechanism* (agent → contract → same pipeline) is designed and the stub was proven in the v1.0 demo; the full skill catalog and real agent runtime are planned. But the design point matters to leadership now: we are building for a world where more of the org can ship safely, not where more of the org has to become a platform engineer.
|
||||
|
||||
---
|
||||
|
||||
## Slide 4 — The Contract
|
||||
|
||||
A 5-line YAML file. This is the entire consumer-facing interface to production.
|
||||
|
||||
```yaml
|
||||
# .acdl/contract.yaml — a static site
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: static-assets
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: my-static-site-assets
|
||||
region: us-east-1
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .acdl/contract.yaml — a microservice
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
module: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
image: my-registry/my-microservice:latest
|
||||
port: 8080
|
||||
env:
|
||||
LOG_LEVEL: info
|
||||
```
|
||||
|
||||
Four fields:
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `uses` | The central pipeline, pinned to a versioned tag |
|
||||
| `module` | A name from the module catalog |
|
||||
| `environment` | `dev`, `qa`, `prod`, or `dr` |
|
||||
| `inputs` | The handful of values that vary per deployment |
|
||||
|
||||
An invalid contract (missing field, unknown module, wrong type) **fails fast at validation** with a clear error — not an opaque failure three stages in.
|
||||
|
||||
> **Speaker notes:** The contract is the API. It is deliberately tiny so that it can be reviewed, validated, and audited. For leadership: this is what makes "declare intent" concrete — it's a one-screen file, not a 300-line Terraform root module.
|
||||
|
||||
---
|
||||
|
||||
## Slide 5 — No Platform Code, No Cloning
|
||||
|
||||
Consumers `uses:` a **versioned** central workflow. The platform fetches itself at run time. The consumer **never touches platform internals.**
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["Consumer repo<br/>app + contract + 'uses:'"] -->|triggers on push to main| B["Platform runner"]
|
||||
B -->|checks out the consumer repo| A
|
||||
B -->|checks out the ACDL platform repo<br/>into the workspace| C["Platform code<br/>(modules, adapters, schemas)"]
|
||||
C --> B
|
||||
B -->|runs the pipeline against<br/>the consumer's contract| D["Consumer's resources in AWS"]
|
||||
```
|
||||
|
||||
- The consumer's CI definition is a thin wrapper — one `uses:` line pointing at a versioned tag.
|
||||
- The runner checks out the consumer repo, then checks out the platform repo into the workspace.
|
||||
- The platform installs its own runtime dependencies. The consumer installs nothing.
|
||||
- The consumer **never clones the platform repo, never invokes platform scripts locally** (optional `--check-only` validation is available but not required for the happy path).
|
||||
|
||||
> **Speaker notes:** The Head of Cloud cares about this: there is no "platform code in every consumer repo" problem. When the platform ships a fix, every consumer on a floating MAJOR.MINOR tag gets it on their next run — no per-repo upgrade project.
|
||||
|
||||
---
|
||||
|
||||
## Slide 6 — Versioned, Predictable Releases
|
||||
|
||||
Consumers control **when** they absorb platform improvements.
|
||||
|
||||
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer on `@v1.6` automatically receives patch updates within the 1.6 line.
|
||||
- **Semantic versioning with a clear contract:** interface changes → MAJOR, behavior changes → MINOR, lifecycle fixes → PATCH.
|
||||
- **A consumer can pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on their own cadence.
|
||||
- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever a consumer has.
|
||||
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags. *(Available today.)*
|
||||
|
||||
> **Speaker notes:** This is the "no surprise upgrades" story. Leadership hears two things: (1) consumers aren't forced to chase the platform, (2) the platform isn't forced to support N forks of every workflow. The versioning discipline is what makes both true.
|
||||
|
||||
---
|
||||
|
||||
## Slide 7 — Instant Feedback
|
||||
|
||||
Developers see **what the platform is doing**, in real time, in their own run logs.
|
||||
|
||||
- **Streamed output by default** — the infrastructure plan, policy-check results, and each `PolicyCheckResult` record (severity, rule ID, pass/fail) flow to stdout. *(Available today.)*
|
||||
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard. *(Available today.)*
|
||||
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque, manual-debugging exercise.**
|
||||
- **A `--quiet` mode** suppresses streaming for log-only contexts.
|
||||
|
||||
> **Speaker notes:** This directly answers "but developers hate platforms that hide what they're doing." The platform is opinionated about *what* runs, not *opaque* about *that* it runs. The PR-comment-after-each-stage pattern is a small thing that compounds into trust.
|
||||
|
||||
---
|
||||
|
||||
## Slide 8 — Deploy Outputs That Just Work
|
||||
|
||||
After a successful deploy, the developer gets their connection information **without hunting for it** — and without secrets leaking into logs.
|
||||
|
||||
- **Human-readable connection strings** posted as a structured GitHub PR comment / job summary. *(Available today.)*
|
||||
- **Runtime-injectable values** written to encrypted Parameter Store (`SecureString`, KMS-encrypted, namespaced `/acdl/{env}/{contractId}/{output_name}`). *(Available today.)*
|
||||
- **No raw secrets in logs** — the platform enforces this by construction.
|
||||
- **Errors become GitHub issues, automatically** — a failed deploy reports through the platform Lambda, which opens (or comments on) an issue on the platform repo. The consumer's only grant is the onboarding-granted Lambda-invoke permission — no separate `issues: write` scope on the consumer side. *(Available today.)*
|
||||
|
||||
> **Speaker notes:** The "errors become issues" point is a DX win that also helps the platform team — every consumer failure is a tracked, queryable artifact, not a lost log line. The Head of DevOps should hear: the platform closes the feedback loop, it doesn't just push a green/red status.
|
||||
|
||||
---
|
||||
|
||||
## Slide 9 — Local Reproducibility
|
||||
|
||||
The entire CI pipeline runs **from the shell**, not just in CI.
|
||||
|
||||
- `scripts/run_ci.sh` mirrors the CI pipeline locally — the same three stages (lint → test → check-only) in sequence. Exits 0 with "CI PIPELINE OK." *(Available today.)*
|
||||
- `scripts/run_platform.sh --check-only` runs the platform offline — **no AWS, no policy engine, no outbox required.** Validates a contract end-to-end before pushing. *(Available today.)*
|
||||
- `--plan-only` runs through the infrastructure plan without applying.
|
||||
- The CI and deploy pipelines are defined by **declarative contracts** (YAML instances validated against JSON Schemas) — a single source of truth that both the GitHub and Gitea workflows implement. A test asserts conformance.
|
||||
|
||||
> **Speaker notes:** This is the "no 'works on my machine' for CI" slide. A developer can reproduce the exact CI behavior locally before pushing. For the Head of Engineering: this shrinks the PR-cycle time because failures are caught pre-push, and it makes the pipeline itself a reviewable artifact (the YAML contract), not tribal workflow code.
|
||||
|
||||
---
|
||||
|
||||
## Slide 10 — Friendly Onboarding
|
||||
|
||||
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully.
|
||||
|
||||
- When a consumer pipeline runs for the first time and **no environment is bound**, the platform detects this and emits a **user-friendly onboarding prompt** instead of failing opaquely. *(Available today.)*
|
||||
- The prompt tells the consumer:
|
||||
1. That no environment is bound to their repo yet.
|
||||
2. What the platform will provision on their behalf (account, network, state, role).
|
||||
3. The expected turnaround for the platform team to grant the environment.
|
||||
4. How to request an environment.
|
||||
- The pipeline then **exits without attempting a deployment** — no partial state, no confusing errors.
|
||||
- **Both onboarding paths end in a sandbox dev submission that must pass the confidence gate** before the consumer is promoted. *(Developer path shipped; citizen developer path planned.)*
|
||||
|
||||
> **Speaker notes:** This looks like a small thing; it's actually a cultural one. The platform's posture is "help me get started," not "you should have known." For the Head of DevOps: this is what drives adoption. Platforms that fail opaquely on first run get routed around.
|
||||
|
||||
---
|
||||
|
||||
## Slide 11 — Safe Promotion Path
|
||||
|
||||
Promoting to a higher environment is **changing one field** — and the platform raises the bar automatically.
|
||||
|
||||
```yaml
|
||||
# dev → qa: change one line
|
||||
uses: acdl/pipelines/deploy.yaml@v1.6
|
||||
environment: qa # QA attestation + confidence >= 0.75
|
||||
```
|
||||
|
||||
| Environment | What the platform adds |
|
||||
|---|---|
|
||||
| dev | Confidence ≥ 0.50, fully autonomous |
|
||||
| qa | QA human attestation + confidence ≥ 0.75 |
|
||||
| prod | SRE human attestation + confidence ≥ 0.90 |
|
||||
| dr | SRE human attestation + confidence ≥ 0.95 + a disaster-recovery drill reference |
|
||||
|
||||
- **No staging environment** — the design deliberately removes the "staging is basically prod but not really" anti-pattern. Dev is the only autonomous environment.
|
||||
- **Separation of duties is enforced** — the QA approver cannot be the prod approver. *(Design shipped; wiring for qa/prod/dr is planned.)*
|
||||
- **Timeout discipline** — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit.
|
||||
|
||||
> **Speaker notes:** The one-field promotion is the DX win; the automatic threshold + attestation raise is the safety win. They are the same feature. For leadership: this is how the platform makes "move fast" and "be safe" stop being a trade-off — the speed is in the ergonomics, the safety is in the gates the consumer can't bypass.
|
||||
|
||||
---
|
||||
|
||||
## Slide 12 — Safe Decommission
|
||||
|
||||
Tearing down a stack is **as deliberate as deploying one** — and just as gated.
|
||||
|
||||
```yaml
|
||||
# Consumer's deploy workflow call
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.8
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
mode: decommission
|
||||
changeRequestId: "CR-2026-001"
|
||||
```
|
||||
|
||||
A 2-step pipeline with **two SRE human-attestation gates** *(available today)*:
|
||||
|
||||
1. **Validate the change request** — the platform queries the CMDB and asserts the CR is `approved` and matches the consumer repo. No CR, no decommission.
|
||||
2. **Disable deletion protection** (resolve with `deletion_protection: false`, plan + apply) → **SRE approves.**
|
||||
3. **Zero all counts + destroy** (the platform zeroes every scalable count, plan + apply) → **a second SRE approves.**
|
||||
4. **Confirmation** — the platform confirms the stack is destroyed.
|
||||
|
||||
**After decommission:**
|
||||
|
||||
- The per-stack encryption key enters a **grace window** (default 30 days) so encrypted data remains recoverable. The key is permanently deleted only after the window expires.
|
||||
- Uptime monitoring is **not** automatically destroyed — it can be left running to watch the decommissioned endpoints go dark, or destroyed separately.
|
||||
|
||||
> **Speaker notes:** The counter-argument to "deletion protection makes cleanup impossible" is this slide. Decommission is a first-class, gated, two-approval flow — not a lock with no key, and not an ungated `terraform destroy`. For the Head of Infrastructure: the CMDB validation means decommission is auditable, not just possible.
|
||||
|
||||
---
|
||||
|
||||
## Slide 13 — Self-Service Module Catalog
|
||||
|
||||
Developers pick from **pre-built, security-reviewed building blocks** — they don't author infrastructure from scratch.
|
||||
|
||||
- **Primitives** — single-purpose resources (S3, VPC, ECS cluster, ECS service, IAM role, load balancer, container registry, CloudFront, WAF, RDS). Each has documented inputs, outputs, usage, compliance extension points, and versioning. *(Available today.)*
|
||||
- **Modules** — composed patterns (a static site with CDN + WAF; a microservice with VPC + ECS + load balancer + registry). *(Available today.)*
|
||||
- **Validated examples per module** — every module ships `simple.yaml` + `complex.yaml` + variation files, validated against the contract schema in CI. Examples cannot drift from the schema silently. *(Available today.)*
|
||||
- **Auto-promotion of patterns** — a thin-composition layer is auto-promoted to the catalog after 3 observed usages. *(Mechanism planned.)*
|
||||
- **Compliance extension points** — each module lists where GDPR, SOX, SOC2, HIPAA, DORA controls will wire in. *(Compliance milestone is planned.)*
|
||||
|
||||
> **Speaker notes:** The catalog is what makes "declare intent" practical — you can only declare a module that exists. For leadership: the catalog is the leverage. One well-reviewed module serves every consumer; a fix to the module serves every consumer on the next run. This is the compounding asset.
|
||||
|
||||
---
|
||||
|
||||
## Slide 14 — The Outcome for Leadership
|
||||
|
||||
What this platform delivers to the organization:
|
||||
|
||||
- **Velocity without sacrificing safety.** The speed is in the ergonomics (a 5-line contract, a one-line `uses:`); the safety is in the gates the consumer cannot bypass.
|
||||
- **Security, observability, and compliance as platform defaults** — not per-team effort, not post-hoc remediation. Encryption, deletion protection, uptime monitoring, policy checks, and evidence are on by construction.
|
||||
- **Auditability as a byproduct, not a project.** Every production change is traceable to a human attestation and a tamper-evident evidence event — captured during the deploy, not reconstructed for the audit.
|
||||
- **Blast radius contained by design.** Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources. One consumer can never affect another.
|
||||
- **The bottleneck moves off the platform team's ticket queue.** A merged change progresses through lower environments without a platform engineer joining a thread. The platform team invests in the platform, not in per-deployment hand-holding.
|
||||
- **A path to the citizen developer.** The same safety envelope that serves a senior engineer is the one that will serve a non-technical consumer — expanding who can ship safely without lowering the bar.
|
||||
|
||||
> **Speaker notes:** Close on the strategic frame. The platform is not "a CI/CD tool" — it is the organizational lever for shipping safely at the pace the business demands, with the security and audit posture the regulators require. Invite questions; the companion deck ("How the Platform Works") covers the internal mechanics in more depth.
|
||||
Reference in New Issue
Block a user