refactor(deploy): externalize compose credentials and subsystem test secrets (FLPATH-4806)

[chadcrum]

Summary

Externalize deploy and subsystem test credentials from committed Compose configuration.

• Load deploy credentials from gitignored deploy/.env.
• Load subsystem test credentials from shared test/subsystem/.env.
• Add .env.example files and Makefile setup prerequisites.
• Gate Keycloak behind the auth Compose profile via AUTH=true.
• Update Keycloak realm imports and deployment documentation.
• Pass .env files explicitly for Compose interpolation.
• Align auth subsystem database setup and test connection handling with the shared credentials.
• Clarify provider and authentication startup behavior.

CI note

The Helm chart job is expected to fail until the companion Helm change synchronizes the generated realm file. This PR intentionally updates the Compose realm file without updating the Helm copy.

https://redhat.atlassian.net/browse/FLPATH-4806

[chadcrum]

cc @jordigilh @vkolodny

[qodo-code-review]

PR Summary by Qodo

Externalize Compose and subsystem test credentials

⚙️ Configuration changes ✨ Enhancement 📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Load deploy and subsystem credentials from gitignored, example-seeded environment files.
• Make Keycloak opt-in through an auth profile and native realm placeholders.
• Document secure startup workflows and align auth tests with configured secrets.

Diagram

graph TD
  A["Env examples"] --> B["Deploy env"] --> C["Compose stack"] --> D["Core services"]
  A --> E["Subsystem env"] --> F["Test stacks"]
  C --> G["Auth profile"] --> H["Keycloak import"]
  B --> G

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Compose secrets

• ➕ Avoid exposing credentials as ordinary container environment variables.
• ➕ Provide explicit secret mounts and clearer sensitive-value boundaries.
• ➖ Require applications and images to support file-based secret inputs.
• ➖ Add complexity for local development and subsystem test bootstrap.

2. External secret manager

• ➕ Centralize rotation, access control, and auditing.
• ➕ Avoid storing credential values in developer-managed files.
• ➖ Introduce infrastructure dependencies unsuitable for lightweight local tests.
• ➖ Increase onboarding and CI configuration complexity.

Recommendation: Gitignored env files are the pragmatic choice for local Compose and subsystem testing because existing containers already consume environment variables and templates preserve simple onboarding. Compose secrets or a secret manager would be preferable for production-grade credentials, while the companion Helm change should restore realm-file synchronization before merge completion.

Files changed (12) +173 / -174

Tests (1) +2 / -2

helpers_test.goUse configured proxy secret in token requests +2/-2

Use configured proxy secret in token requests

• User and service-account token helpers now submit the suite's configured proxy secret instead of a hard-coded client credential.

test/subsystem/auth/helpers_test.go

Documentation (2) +73 / -61

README.mdDocument credential setup and optional Keycloak startup +7/-4

Document credential setup and optional Keycloak startup

• The local-run guide now requires creating deploy/.env and distinguishes the default stack from AUTH=true startup. Provider examples are updated for profile-based startup.

README.md

RUN.mdRevise Compose, authentication, and provider workflows +66/-57

Revise Compose, authentication, and provider workflows

• The deployment guide now explains deploy/.env creation, optional Keycloak activation, provider configuration, and native realm placeholders. It also clarifies Kubernetes Secret requirements and credential ownership.

deploy/RUN.md

Other (9) +98 / -111

MakefileAdd optional auth profile and subsystem env bootstrap +13/-4

Add optional auth profile and subsystem env bootstrap

• Compose targets now enable Keycloak only when AUTH=true and default provider startup explicitly when no profile list is supplied. A shared prerequisite copies test/subsystem/.env.example into the gitignored subsystem environment before test stacks start.

Makefile

.env.exampleDefine deploy credential and profile configuration template +34/-39

Define deploy credential and profile configuration template

• The template now contains required database values, an opt-in authentication block, and optional provider settings. It serves as the committed source for creating the gitignored deploy/.env.

deploy/.env.example

compose.yamlLoad deploy credentials externally and profile Keycloak +17/-26

Load deploy credentials externally and profile Keycloak

• Core credential-consuming services now load deploy/.env instead of embedding credential defaults. Keycloak becomes an auth-profile service using native realm import, while control-plane startup no longer depends on it by default.

deploy/compose.yaml

realm-export.jsonParameterize Keycloak client and user secrets +2/-2

Parameterize Keycloak client and user secrets

• The realm import replaces committed proxy and development-user credentials with Keycloak-native environment placeholders. This removes the custom shell substitution path from Compose startup.

deploy/keycloak/realm-export.json

.env.exampleAdd shared subsystem credential template +12/-0

Add shared subsystem credential template

• A new template centralizes database, Keycloak, OIDC, proxy, and bootstrap-admin values for all subsystem Compose stacks. Make targets copy it to a gitignored shared environment file when absent.

test/subsystem/.env.example

docker-compose.yamlExternalize auth subsystem credentials +8/-19

Externalize auth subsystem credentials

• Postgres, Keycloak, and control-plane now consume the shared subsystem environment file. Keycloak uses the upgraded image and native realm import rather than generating a substituted realm file in its entrypoint.

test/subsystem/auth/docker-compose.yaml

docker-compose.yamlLoad catalog subsystem database credentials from shared env +4/-7

Load catalog subsystem database credentials from shared env

• The catalog Postgres and application services now consume test/subsystem/.env. Embedded database credential defaults are removed, and the health check reads the container environment.

test/subsystem/catalog/docker-compose.yaml

docker-compose.yamlLoad policy subsystem database credentials from shared env +4/-7

Load policy subsystem database credentials from shared env

• The policy Postgres and application services now consume test/subsystem/.env. Embedded database credential defaults are removed, and the health check reads the container environment.

test/subsystem/policy/docker-compose.yaml

docker-compose.yamlLoad service-provider subsystem credentials from shared env +4/-7

Load service-provider subsystem credentials from shared env

• The service-provider Postgres and control-plane services now consume test/subsystem/.env. Embedded database credential defaults are removed, and the health check uses the injected PostgreSQL user.

test/subsystem/sp/docker-compose.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Auth setting ignores deploy env ✓ Resolved 🐞 Bug ≡ Correctness

Description

make compose-up AUTH=true starts Keycloak but does not load deploy/.env for Compose
interpolation, so ${AUTH_DISABLED:-true} overrides the control-plane's env_file value with
true. Following the documented auth workflow therefore leaves authentication disabled, and other
interpolation-only deploy settings such as image tags and provider kubeconfig paths are likewise
ignored.

Code

deploy/compose.yaml[68]

+    env_file: .env

Evidence

The Make target runs -f deploy/compose.yaml from the repository root without selecting
deploy/.env, while the newly added env_file feeds only the container. The compose environment
block explicitly sets AUTH_DISABLED from interpolation, and application startup uses that
resulting value to bypass all authentication.

Makefile[53-61]
deploy/compose.yaml[61-75]
deploy/.env.example[11-19]
internal/app/run.go[223-243]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documented Make targets invoke Compose from the repository root, while `env_file` only configures container runtime variables. Compose-file expressions such as `${AUTH_DISABLED:-true}` must be interpolated from `deploy/.env`; otherwise the explicit `environment` entry overrides the runtime env-file value and auth remains disabled.

## Issue Context
Keep `deploy/.env` as the single documented source for deploy settings and ensure all supported Compose commands receive it for interpolation.

## Fix Focus Areas
- Makefile[53-61]
- deploy/compose.yaml[61-75]
- deploy/RUN.md[19-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Custom auth credentials break tests ✓ Resolved 🐞 Bug ≡ Correctness

Description

The auth Compose services consume credentials from test/subsystem/.env, but `make
auth-subsystem-test` starts the host-side Ginkgo suite without exporting that file. Changing the
database credentials, Keycloak admin password, or proxy secret therefore leaves the tests using
hard-coded or default values, causing database connections or token requests against the configured
stack to fail.

Code

test/subsystem/auth/docker-compose.yaml[6]

+    env_file: ../.env

Evidence

The prerequisite creates test/subsystem/.env, and the added Compose env_file loads it into
services such as PostgreSQL, but the separate Make recipe runs Ginkgo directly without sourcing or
exporting the file. The test process independently defaults AUTH_PROXY_SECRET and the database
connection, while the Keycloak helper always submits literal admin/admin credentials, proving
that customized values in the shared file cannot reach the host-side clients.

test/subsystem/auth/docker-compose.yaml[4-14]
Makefile[109-113]
make/auth.mk[6-13]
test/subsystem/auth/suite_test.go[34-44]
test/subsystem/auth/helpers_test.go[21-32]
test/subsystem/.env.example[2-10]
make/auth.mk[4-13]
test/subsystem/auth/docker-compose.yaml[20-30]
test/subsystem/auth/suite_test.go[34-39]
test/subsystem/auth/helpers_test.go[21-29]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description

`test/subsystem/.env` configures the auth Compose containers, but the host-side Ginkgo suite does not load it. Load the same file for the test command and remove hard-coded credential assumptions so the stack and tests use one source for custom database credentials, Keycloak admin credentials, and the proxy secret.

## Issue Context

The prerequisite creates the shared environment file, and Compose injects it into its services through `env_file`; this does not export the variables to the separate Make recipe that runs Ginkgo. The suite defaults its database connection and proxy secret from the process environment, while the Keycloak administration helper uses literal `admin` credentials, so customized file values are unavailable to the host-side tests.

## Fix Focus Areas

- Makefile[109-113]
- make/auth.mk[6-13]
- test/subsystem/auth/docker-compose.yaml[6-6]
- test/subsystem/auth/suite_test.go[34-44]
- test/subsystem/auth/helpers_test.go[21-29]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

Review mode: 🧠 Deep: This security-sensitive credential externalization changes Compose profiles, env propagation, Keycloak realm substitution, and multiple deploy/subsystem test paths, creating many independent, easy-to-miss behavioral risks.

Tip of the day

💡 Did you know, you can ask Qodo to dismiss a finding you disagree with, with your reason on record

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[vkolodny]

@chadcrum fyi — once this merges, deploy/.env becomes required (compose hard-fails without it, tested locally). That'll break deploy-dcm.sh and the flightpath-dcm-deploy Jenkins job, since it calls podman-compose directly and never creates that file today. Not a problem with this PR, just needs a follow-up on our side before/after merge so the pipeline doesn't break on the next run.

[chadcrum]

@chadcrum fyi — once this merges, deploy/.env becomes required (compose hard-fails without it, tested locally). That'll break deploy-dcm.sh and the flightpath-dcm-deploy Jenkins job, since it calls podman-compose directly and never creates that file today. Not a problem with this PR, just needs a follow-up on our side before/after merge so the pipeline doesn't break on the next run.

@vkolodny I'll update those today.

[chadcrum]

@gciavarrini would you mind approving unless there is anything else? thanks!

[LinskId]

once comment resolved, depends on #66