Draft: docs: add self-managed GATE install guide (IAM data access + GLAZ)

Matthias Käpplerrequested to merge
docs/self-managed-gate-install into main

What

Adds docs/self-managed-install-gate.md — a self-managed install guide for the GATE auth layer that gates Artifact Registry (AR): the iam-data-access gRPC service and the GLAZ authorization sidecar.

It is the companion to the AR self-managed CNG baseline (gitlab-org/ops/artifact-registry, MR !921), which installs AR without auth and explicitly defers the GATE components to a companion doc. This MR is that companion.

Why

To document the as-is customer flow for running iam-data-access + GLAZ from their Fairway-generated charts on top of an existing GitLab CNG + AR install, so reviewers can flag steps that are functionally untenable before closed beta — same intent and structure as the AR baseline doc.

Scope

Nine steps: provision IAM's DB → namespace + secrets → service-token coordination with GitLab → CONFIG_TOML → Helm values → install → gRPC verification → enable the GLAZ sidecar in AR → retire the AR bootstrap token. Plus a known-gaps table and open items.

Verification level (please read — this is deliberately honest)

  • Verified live on the caproni dev cluster: the running iam-data-access service is healthy — migrations applied, tokenauth: JWKS fetch OK, grpc.health.v1.Health/Check → SERVING, list/Health RPCs work (this is how the stale update.v1.* → gitlab.iam.update.v1.* service naming was caught).
  • Derived, NOT run end to end: the from-scratch sequence in steps 1–6 (manual CREATE DATABASE, hand-built secrets, the iam-values.yaml + helm upgrade --install). The rig provisions IAM via its own tooling (CloudNativePG-managed DB, a Fairway values file), so the Helm values shape / chart version / exact commands are plausible-from-sources but unverified in a clean room.
  • Not run at all: the GLAZ steps 8–9 — the glaz image is linux/amd64 only and could not be exercised on the arm64 dev cluster.

The doc's status table states all of the above.

Open questions for discussion

  1. Right home? This lives in the iam repo docs/. Alternatives: fold into AR MR !921, or a stacked MR there. Where should GATE-for-AR install docs live?
  2. docs/index.md is currently scoped to "Rails Development Setup," so this K8s install guide doesn't fit that heading — left untouched. Add a new section / deployment-docs grouping?
  3. Known gaps worth prioritizing (full table in the doc): iam-data-access + GLAZ images are amd64-only; the service-token cross-release coordination (GitLab chart ≥ 10.2); environment can't secretKeyRef (secrets end up plaintext in CONFIG_TOML); keys_url endpoint skew (/-/cloud_connector/keys vs /oauth/discovery/keys); [platform.cors] allowed_origins required for a gRPC-only service; DB name/user hardcoded to iam-service.
  4. Should we do a clean-room install to promote steps 1–6 from "derived" to "verified" before merging?

🤖 Drafted by Claude Code.

Merge request reports