docs(designs): add AWS lab account and Keycloak designs#12
Merged
Conversation
Proposes a dedicated AWS Organization (management + lab member accounts) in us-west-2 as the lab's durable off-lab trust anchor. Covers account layout, IAM Identity Center with a local identity store and WebAuthn MFA, a single public-subnet VPC at 172.16.0.0/16 with a Tailscale subnet router using workload identity federation, a Route 53 private zone for glab.lol mirrored to an in-lab CoreDNS zonefile for cold-start and outage resilience, and a secrets bootstrap chain (KMS as a SOPS recipient plus a GitHub App key in SSM) that terminates every instance-side identity at a single IAM role. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Proposes Keycloak as the lab's central identity provider, deployed via Docker Compose on a dedicated t4g.small in the lab AWS account, colocated with Postgres, served at id.glab.lol. A single lab realm federates GitHub as its only OIDC upstream. Declarative configuration is reconciled from git via keycloak-config-cli; runtime state is backed up nightly to S3 with a rolling retention window and pulled locally to the Synology NAS. Disaster recovery is rebuild-first, with a documented same-hostname restore fallback. Includes a per-service break-glass matrix (Talos API, Argo CD admin, Vault recovery keys, local Identity Center user, etc.) so identity outages do not cascade into service outages. Also updates the designs index to list both the AWS Lab Account and Keycloak documents. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two paired design documents that capture the lab's off-lab trust anchor strategy:
AWS Lab Account (
docs/docs/designs/aws-lab-account.md) — dedicated AWS Organization (management + lab member accounts) inus-west-2as the durable trust anchor. IAM Identity Center with a local identity store, a single-AZ VPC at172.16.0.0/16, a Tailscale subnet router authenticated via workload identity federation, a Route 53 private zone forglab.lolmirrored to an in-lab CoreDNS zonefile, and a secrets bootstrap chain (KMS as SOPS recipient + GitHub App key in SSM) where every machine identity terminates at a single IAM role.Keycloak (
docs/docs/designs/keycloak.md) — Keycloak + colocated Postgres via Docker Compose on a dedicatedt4g.small, served atid.glab.lol. Singlelabrealm federating GitHub OIDC only.keycloak-config-clireconciles declarative state from git; runtime state backs up nightly to S3 with Synology pull. Disaster recovery is rebuild-first. Includes a per-service break-glass matrix so identity outages do not cascade.Both docs are deliberately architecture-shaped — contracts and rationale, not specific IAM JSON, Tailscale ACLs, OpenTofu module layout, monitoring, or per-client Keycloak configuration.
Also updates
docs/docs/designs/index.mdto list both documents.Test plan
aws-lab-account.mdinternal link to./keycloak.mdresolves.keycloak.mdinternal link to./aws-lab-account.mdresolves.docs/docs/designs/index.mdrenders both new entries in order.🤖 Generated with Claude Code