linode / linode/apl-core

PRD: Make Keycloak optional

Open
#3,538 0 comments 0 reactions 0 assignees View on GitHub
not-ready ready-for-agent
Dominant language
Go Template
Stars
2.3k
Forks
186
Avg merge
3d 11h
Merged PRs (30d)
66

Description

## Problem Statement

Keycloak is not optional. Its deployment, its operator, its database and their supporting resources are installed unconditionally, and the derived layer forces its enabled flag to true regardless of what a user configures.

For a new installation using Dex that is pure waste: a Java application, an operator and a replicated database, none of which anything authenticates against.

The change is delicate in the other direction. Existing clusters depend on Keycloak, and their values do not say so, because until now there was nothing to say. Flipping the default without preparing them would remove a running identity provider during an upgrade.

## Solution

Make Keycloak an ordinary optional application, and prepare existing clusters before changing the default.

Every Keycloak release becomes conditional on its enabled flag, and the derived layer stops overriding that flag. New installations default to Dex and do not install Keycloak. The alert that watches the Keycloak database backup is gated on the same flag, so a disabled Keycloak does not produce alerts about a database that no longer exists.

The ordering matters more than the mechanism. A values migration writes the enabled flag into existing clusters, so that by the time the default changes their configuration already states what they are running. An upgrade must never be the thing that decides an existing cluster's identity provider.

## Acceptance Criteria

1. **GIVEN** default values, **WHEN** the platform is rendered, **THEN** no Keycloak workload, operator or database is produced.
2. **GIVEN** Keycloak is enabled, **WHEN** the platform is rendered, **THEN** its deployment, operator, database and supporting resources are produced as they are today.
3. **GIVEN** Keycloak is disabled, **WHEN** the platform is rendered, **THEN** the alert covering its database backup is absent.
4. **GIVEN** a cluster installed before this change, **WHEN** it is upgraded, **THEN** the values migration records that Keycloak is enabled before defaults are applied, and Keycloak keeps running.
5. **GIVEN** that upgraded cluster, **WHEN** the platform is rendered afterwards, **THEN** its output is unchanged from before the upgrade.
6. **GIVEN** a cluster with Keycloak disabled and `otomi.issuer: dex`, **WHEN** the platform is rendered, **THEN** every consumer points at Dex. Disabling Keycloak does not itself select an issuer — `otomi.issuer` (#3537) does that independently, so Dex can also be enabled and unused while Keycloak stays the issuer.
7. **GIVEN** the configuration schema, **WHEN** it is validated, **THEN** the Keycloak enabled flag is a documented property with a default, not an undeclared value.

## Testing

- Render with each issuer and confirm the expected workloads appear and disappear.
- The migration needs a test of its own: take values as an existing cluster would have them, run the migration, and assert the enabled flag is written. Migration tests already exist and are the prior art.
- Criterion 5 is the one that protects the fleet and deserves an explicit before-and-after render, not just a code review.

## Out of Scope

- Removing Keycloak from the repository. Both implementations remain supported.
- Migrating users, or changing the issuer on a cluster that is already running.
- Coupling the enabled flag to the issuer. `apps.keycloak.enabled` means only "Keycloak is running here" — which issuer is active is `otomi.issuer` (#3537), a separate field, so both apps can be enabled at once.
- Deleting Keycloak's data when it is disabled. Disabling stops deploying it; it does not destroy a database.

## Further Notes

- Namespaces are created for every declared application regardless of whether it is enabled, which is existing behaviour. A disabled Keycloak therefore still leaves empty namespaces behind. Consistent with the rest of the platform, and not changed here.
- The derived layer currently sets Keycloak's enabled flag to true unconditionally, which silently overrides user input. Removing that override is part of this change and is worth reviewing on its own, since anything else relying on the flag being always true would be exposed by it.

## Dependencies

Depends on #3537 — Keycloak cannot be made optional until an alternative issuer can be selected.

Blocks #3540.

Contributor guide

Open the contributing guide

Research direction

Start with the existing migration tests, then trace the Keycloak release definitions, derived layer, configuration schema, and database-backup alert. Render the platform with each issuer and verify the expected resources, alert behavior, and unchanged upgraded-cluster output. Add a migration test proving existing clusters record Keycloak as enabled before defaults apply.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
authentication, infrastructure
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.