Skip to content

ADR-010-keycloak-gitops-sync.md

Latest commit

 

History

History
104 lines (80 loc) · 6 KB

ADR-010-keycloak-gitops-sync.md

File metadata and controls

104 lines (80 loc) · 6 KB

ADR-010: Keycloak Multi-Region with GitOps Sync

Status: Accepted

Date: 2026-01-25

Context

With multi-region and multi-account architecture (HML/PRD), Keycloak needs to have the same configuration (realms, clients, roles) across all regions within the same account, but keep sessions isolated. Additionally, changes in HML should not affect PRD automatically (per ADR-006).

Options Considered

  1. Single global Keycloak (all regions point to a centralized Keycloak)
  2. Keycloak Cross-DC Replication (distributed Infinispan)
  3. Keycloak per region with GitOps sync (config as code)
  4. GitOps sync cross-account (HML and PRD synchronized)

Decision

Adopt Keycloak per region with GitOps sync, separated by account. Each region has its own Keycloak instance, and realm configuration is synchronized via Git only within the same account (cross-region, not cross-account).

Rationale

  • Low latency: Local authentication in the user's region
  • Failure isolation: Keycloak in one region does not affect others
  • Account isolation: Changes in HML do not affect PRD automatically
  • Progressive rollout: Test configurations in HML before promoting to PRD
  • GitOps: Versioned, auditable, and consistent configuration
  • Simplicity: Avoids complexity of distributed Infinispan cross-region

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Git Repository                                     │
│                      platform-keycloak/realms/                               │
├─────────────────────────────────┬───────────────────────────────────────────┤
│     realms/helpdev-hml/         │         realms/helpdev-prd/               │
│     (HML Account Config)        │         (PRD Account Config)              │
└────────────────┬────────────────┴──────────────────┬────────────────────────┘
                 │                                    │
                 ▼                                    ▼
    ┌────────────────────────┐         ┌─────────────────────────────────────┐
    │   AWS Account: HML     │         │        AWS Account: PRD             │
    │                        │         │                                     │
    │  ┌──────────────────┐  │         │  ┌──────────────┐ ┌──────────────┐  │
    │  │ Argo CD          │  │         │  │ Argo CD      │ │ Argo CD      │  │
    │  │ hml/us-east-1    │  │         │  │ prd/us-east-1│ │ prd/sa-east-1│  │
    │  └────────┬─────────┘  │         │  └──────┬───────┘ └──────┬───────┘  │
    │           │            │         │         │                │          │
    │           ▼            │         │         ▼                ▼          │
    │  ┌──────────────────┐  │         │  ┌──────────────┐ ┌──────────────┐  │
    │  │ Keycloak         │  │         │  │ Keycloak     │ │ Keycloak     │  │
    │  │ hml/us-east-1    │  │         │  │ prd/us-east-1│ │ prd/sa-east-1│  │
    │  │ (RDS)            │  │         │  │ (RDS)        │ │ (RDS)        │  │
    │  └──────────────────┘  │         │  └──────────────┘ └──────────────┘  │
    └────────────────────────┘         └─────────────────────────────────────┘

Synchronization Rules

ArgoCD Instance Source Path Syncs To
hml/us-east-1 realms/helpdev-hml/ Keycloak hml/us-east-1
prd/us-east-1 realms/helpdev-prd/ Keycloak prd/us-east-1
prd/sa-east-1 realms/helpdev-prd/ Keycloak prd/sa-east-1

Principle: Same folder in Git → same configuration → synchronized between regions of the same account.

What is Synchronized

  • Realms (realm.json)
  • Clients (argocd, grafana, backstage, service clients)
  • Roles and permissions
  • Identity Providers (GitHub SSO)
  • Client scopes

What is NOT Synchronized

Isolated per region (runtime data)

  • User sessions
  • Refresh tokens
  • User data (if applicable)
  • Audit logs

Isolated per account (configuration)

  • Realm configurations between HML and PRD (manual promotion via PR)

HML → PRD Promotion Workflow

  1. Developer commits change to realms/helpdev-hml/
  2. Argo CD syncs to HML cluster
  3. Testing and validation in HML environment
  4. PR to copy changes from realms/helpdev-hml/ → realms/helpdev-prd/
  5. Code review by Platform Team + Security Team
  6. Merge triggers Argo CD sync to PRD clusters (all regions)

Consequences

  • Keycloak configuration in platform-keycloak/realms/{account}/ (JSON)
  • keycloak-config-cli as init container to import config
  • Argo CD in each account/region monitors specific repo path
  • New client created via Backstage → commit to Git → sync across regions of the same account
  • Promotion to PRD requires PR and approval