From f03722331b3e5d858a797b043010c02fd69234de Mon Sep 17 00:00:00 2001 From: Alexander Amiri Date: Tue, 10 Mar 2026 23:12:46 +0100 Subject: [PATCH] Add registry restructure docs and fix deployment status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document hero membership system (groups/, heros.yaml, Sheets sync) - Document registry as source of truth for all memberships - Document Google Workspace account auto-creation for heroes - Fix deployment status: all Terraform applied, Cognito pools deployed - Internal Cognito pool connected to Google IdP - Rename javabin register → javabin register-team --- CLAUDE.md | 24 +++++++++++++++ README.md | 4 +-- auth.md | 15 ++++++---- getting-started.md | 70 +++++++++++++++++++++++++++++++++++++++----- platform-overview.md | 23 ++++++++++++--- 5 files changed, 117 insertions(+), 19 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a036dc3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# CLAUDE.md — Javabin Docs + +Developer-facing documentation for the Javabin platform and JavaZone systems. +This is a standalone docs repo — no build system, just Markdown files. + +## Files + +| File | What | +|------|------| +| `README.md` | Index of all javaBin systems (platform, JavaZone apps, java.no) | +| `platform-overview.md` | Platform architecture, components, how apps get CI/CD | +| `getting-started.md` | How to register a team, add repos, get automated CI/CD | +| `auth.md` | Identity model: Identity Center, GitHub OIDC, Cognito pools | + +## Key Facts + +- Teams are the registration unit. Register via `teams/{name}.yaml` in `javaBin/registry`. +- There is no separate app registration. Apps just need `app.yaml` at repo root and membership in a GitHub team. +- Platform Terraform and reusable workflows live in `javaBin/platform`. + +## Related + +- [javaBin/platform](https://github.com/javaBin/platform) — infrastructure code +- [javaBin/registry](https://github.com/javaBin/registry) — team registration diff --git a/README.md b/README.md index f772ea1..6a32d3c 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,10 @@ Shared AWS infrastructure for CI/CD, compute, and monitoring. See: - [Platform Overview](platform-overview.md) — architecture, components, how it works -- [Getting Started](getting-started.md) — how to register an app and get automated CI/CD +- [Getting Started](getting-started.md) — how to register a team and get automated CI/CD - [Authentication](auth.md) — identity model (OIDC, Identity Center, Cognito) - [Platform repo](https://github.com/javaBin/platform) — Terraform code and reusable modules -- [Registry](https://github.com/javaBin/registry) — app and team registration +- [Registry](https://github.com/javaBin/registry) — team registration and hero membership ## JavaZone diff --git a/auth.md b/auth.md index 5c22080..1903bcd 100644 --- a/auth.md +++ b/auth.md @@ -2,6 +2,10 @@ How identity and access control work in the Javabin platform. +## Google Workspace Accounts + +All javaBin heroes get a `@java.no` Google Workspace account, auto-created when their entry is added to `groups/heros.yaml` in the registry. An invite is sent to their personal email. Heroes can also request an email alias (e.g., `alex@java.no`) via PR. + ## Console Access: IAM Identity Center + Google Workspace IAM Identity Center provides AWS console and CLI access for javaBin volunteers, federated via Google Workspace SAML. @@ -9,9 +13,10 @@ IAM Identity Center provides AWS console and CLI access for javaBin volunteers, - Google Workspace groups map to IAM Identity Center permission sets - Volunteers sign in with their `@java.no` Google account - Access is scoped by 3 permission sets: admin, developer, read-only -- 2FA is enforced on all Identity Center users +- Group membership is managed in `groups/heros.yaml` — the `memberships` field determines which groups a hero belongs to +- Groups with `identity_center: true` in `groups/groups.yaml` are synced to Identity Center -**Status**: Live. IAM Identity Center deployed with SAML federation to Google Workspace. +**Status**: Deployed. Terraform applied from `terraform/org/`. ## CI/CD Access: GitHub OIDC @@ -39,7 +44,7 @@ auth: internal # or: external, both, none The platform creates a Cognito app client and passes the client ID/secret via environment variables. -**Status**: Deployed. Both Cognito pools are managed in Terraform (`terraform/platform/identity/`). Apps that need auth can use Cognito or continue using Auth0 at `login.javazone.no`. +**Status**: Deployed. Internal pool connected to Google Workspace as IdP. External pool deployed but not yet connected to Google. Apps currently use Auth0 at `login.javazone.no` (migration pending). ## Developer CLI Authentication @@ -54,7 +59,7 @@ The `javabin` CLI (4 commands: init, register, status, whoami) authenticates via |---------|-----------|--------| | AWS Console | Identity Center + Google SAML + 2FA | Deployed | | CI/CD | GitHub OIDC | Deployed | -| App users (internal) | Cognito internal pool | Deployed | -| App users (external) | Cognito external pool | Deployed | +| App users (internal) | Cognito internal pool + Google IdP | Deployed | +| App users (external) | Cognito external pool | Deployed (Google IdP not yet connected) | | Legacy app auth | Auth0 (`login.javazone.no`) | Active | | Developer CLI | gh CLI + AWS credential chain | Implemented | diff --git a/getting-started.md b/getting-started.md index e4dc306..052b4fe 100644 --- a/getting-started.md +++ b/getting-started.md @@ -1,6 +1,6 @@ # Getting Started with the Javabin Platform -How to register a team, create a service, and get automated CI/CD. +How to register a team, add repos, and get automated CI/CD. ## Prerequisites @@ -16,12 +16,12 @@ brew install javaBin/tap/javabin javabin init # Register your team (opens a PR against javaBin/registry) -javabin register +javabin register-team ``` The `init` command scaffolds a new service repo from [javaBin/app-template](https://github.com/javaBin/app-template), including `app.yaml` and `Dockerfile`. -The `register` command prompts for team details and creates a registration PR automatically. +The `register-team` command prompts for team details and creates a team registration PR automatically. Other commands: `javabin status` (check platform status), `javabin whoami` (show current identity). @@ -37,6 +37,7 @@ description: What your team works on members: - google: firstname.lastname github: github-username +budget_nok: 5000 # Optional, defaults to 500 NOK/mo ``` - `google_group` is derived automatically as `team-{name}@java.no` @@ -47,20 +48,41 @@ members: A platform owner (`@javaBin/platform-owners`) reviews and merges it. This triggers team provisioning (Google Group, GitHub team, Cognito group, IAM). -### Step 3: Add app.yaml to your repo +### Step 3: Add repos to your team + +After your team is provisioned, add your repos to the GitHub team: + +**Via GitHub UI:** +1. Go to [github.com/orgs/javaBin/teams](https://github.com/orgs/javaBin/teams) +2. Select your team +3. Go to the **Repositories** tab +4. Click **Add repository** and select your repo + +**Via CLI:** +```bash +gh api orgs/javaBin/teams/TEAM/repos -f owner=javaBin -f repo=REPO -f permission=push +``` + +Replace `TEAM` with your team name and `REPO` with the repository name. + +### Step 4: Add app.yaml to your repo Add an `app.yaml` to your repo root to configure compute, routing, and resources. See the [app.yaml reference](https://github.com/javaBin/platform/blob/main/docs/app-yaml-reference.md). +For CI/CD to work on a repo, the repo needs: +- To be under a registered team (GitHub team membership) +- An `app.yaml` at the repo root + ## What Happens After Registration 1. The platform provisions: - A **Google Group** (`team-{name}@java.no`) - A **GitHub team** with all members as maintainers - - An **IAM role** your CI pipeline assumes via GitHub OIDC - - An **ECR repository** for your Docker images + - A **Cognito group** for identity management + - **IAM resources** your CI pipeline assumes via GitHub OIDC - A **budget alert** for cost monitoring -2. Push to `main`. The platform CI pipeline automatically: +2. After you add a repo to your team and include an `app.yaml`, every push to `main` triggers the full pipeline: - Builds your code (Java/Maven or TypeScript/pnpm) - Builds and pushes a Docker image - Plans and applies Terraform infrastructure @@ -74,12 +96,44 @@ Use the CLI or start from [javaBin/app-template](https://github.com/javaBin/app- 1. Run `javabin init` (recommended), or click **"Use this template"** on GitHub 2. Customize `app.yaml` and `Dockerfile` 3. Register your team in the registry (see above) -4. Push — CI takes over +4. Add the repo to your GitHub team (see Step 3 above) +5. Push — CI takes over ## Multi-Environment Support `app.yaml` supports an `environments:` block for dev/prod separation. If omitted, a single production environment is created. See the [app.yaml reference](https://github.com/javaBin/platform/blob/main/docs/app-yaml-reference.md#environments) for details. +## Hero Membership + +The registry is also the source of truth for all javaBin hero volunteers (~70 people/year). This is separate from team registration — teams are for app developers who need AWS access, heroes are all active volunteers. + +### How hero membership works + +1. Board sends yearly Google Forms for hero applications +2. Responses go to a Google Sheet, board marks approved heroes +3. Board triggers a sync (Apps Script button or GitHub Actions workflow) +4. Sync creates a PR on the registry updating `groups/heros.yaml` +5. PR reviewed and merged — triggers provisioning: + - Google Workspace accounts auto-created for new heroes + - All heroes added to `helter@java.no` + - Heroes added to their membership groups (styret, javazone, pkom, kodesmia, region, etc.) + +### Registry structure + +``` +registry/ + teams/ # App developer teams (AWS IAM, budgets, GitHub teams) + groups/ + groups.yaml # All group definitions (Google email, Cognito/IC flags) + heros.yaml # All hero members (name, email, alias, memberships) +``` + +- `groups.yaml` defines what groups exist and their properties +- `heros.yaml` defines who the heroes are and which groups they belong to +- Being in `heros.yaml` = member of `helter` (implicitly) +- The `memberships` field controls additional group assignments +- Heroes can PR an email alias (e.g., `alex@java.no`) + ## No Per-Repo Workflow Files The platform provides reusable workflows. Your repo does not need its own `.github/workflows/` directory for standard CI/CD. The entrypoint workflow (`javabin.yml`) detects your repo contents and runs the appropriate build and deploy steps. diff --git a/platform-overview.md b/platform-overview.md index 4c2dbeb..d56e6af 100644 --- a/platform-overview.md +++ b/platform-overview.md @@ -37,7 +37,7 @@ Seven Terraform sub-modules manage shared resources: | **compute** | ECS Fargate cluster (`javabin-platform`), ECR base config | | **monitoring** | SNS topics, EventBridge rules, AWS Config, GuardDuty, Security Hub | | **lambdas** | 6 Lambda functions for alerts, cost reporting, compliance, cleanup | -| **identity** | IAM Identity Center (SAML + Google Workspace), 3 permission sets, Cognito user pools, 2FA enforced | +| **identity** | Cognito user pools (internal + external). Internal pool connected to Google IdP. Identity Center is in `terraform/org/` (deployed) | ### Reusable Modules (`terraform/modules/`) @@ -64,18 +64,33 @@ App repos call `javaBin/platform/.github/workflows/javabin.yml` as their CI entr | `daily-cost-check` | Daily schedule (08:00 UTC) | Spike detection, silent if no anomalies | | `compliance-reporter` | EventBridge (resource create/run) | Reports untagged resources to Slack | | `override-cleanup` | Hourly schedule | Deletes stale SSM override tokens | -| `team-provisioner` | Registry merge (repository_dispatch) | Syncs teams across Google, GitHub, Cognito, IAM | +| `team-provisioner` | Registry merge | Syncs Google Groups, GitHub teams, AWS Budgets, Cognito, Identity Center. Also handles hero provisioning (Workspace accounts, aliases, group membership) | ## How Apps Get CI/CD 1. Developer creates a repo from `javaBin/app-template` (or runs `javabin init`) 2. Registers their team in `javaBin/registry` (PR with `teams/{name}.yaml`) 3. Platform owner merges — team-provisioner syncs Google Group, GitHub team, Cognito, IAM -4. Developer adds `app.yaml` to repo root with service config -5. Every push to `main` triggers the full pipeline: build, plan, review, deploy +4. Developer adds the repo to their GitHub team (via GitHub UI or `gh api orgs/javaBin/teams/TEAM/repos`) +5. Developer adds `app.yaml` to repo root with service config +6. Every push to `main` triggers the full pipeline: build, plan, review, deploy + +The registry is the IAM gate: unregistered teams have no IAM role, so CI can't deploy. For CI/CD to work, a repo must be under a registered team and have an `app.yaml` at root. No per-repo workflow files needed. The platform handles everything. +## Registry: Source of Truth for Memberships + +The [registry](https://github.com/javaBin/registry) serves two purposes: + +**Teams** (`teams/`) — app developer teams that need AWS access. Each team gets an IAM role, budget, GitHub team, and Google Group. + +**Groups & Heroes** (`groups/`) — organizational membership for all javaBin volunteers: +- `groups.yaml` defines all groups (helter, styret, javazone, pkom, kodesmia, region, drift, admin, developers, etc.) with their properties (Google Workspace email, Cognito/Identity Center flags) +- `heros.yaml` defines all hero members with their group assignments + +Changes to `groups/` trigger provisioning: Google Workspace account creation, group membership sync, email aliases, and Cognito/Identity Center sync where configured. Heroes are synced from a yearly Google Sheets application process. + ## AWS Account - **Account**: (private — see platform repo)