Deployment-Config Remediation

Who this is for

generatorSupported: false, inScope: true is a real, common category, not an edge case: an upstream binary or container image (Keycloak, nginx, Envoy, a managed database/queue image, a Helm-installed operator) with no application source in the repo for /otel-instrument to bootstrap, but a genuine deployed workload with its own native OpenTelemetry (or OTel-adjacent) configuration surface — usually environment variables or CLI flags read at container start.

/otel-evaluate's brownfield-auditor already audits these services well: it reads service.deployment.configFiles (the Kubernetes manifest, Dockerfile, docker-compose file, Helm values) the same way it does for any other service, and reports missing/misconfigured native OTel settings as ordinary findings (mostly CF — telemetry configuration). What was missing is a way to turn those findings into a concrete diff, the same way /otel-instrument --fix <ids> does for a generatorSupported: true service's source files. This skill is that missing half, dispatched by /otel-remediate.

v1 scope: Keycloak only

Only Keycloak is supported in v1. This list is deliberately a table, not prose, so adding a second target later is an addition, not a rewrite — but do not guess at an unlisted target's config surface by analogy; every binary's flags are different, and a wrong guess here writes config that doesn't do what it claims. For anything not in the table below, /otel-remediate must refuse by name by name, the same "wrong code is worse than no code" principle instrumentation-gen already applies to an unsupported language/runtime — do NOT emit a diff for a target this skill doesn't cover.

Keycloak: native OTel configuration surface

Keycloak is Quarkus-based; its runtime config properties (kebab-case, e.g. tracing-enabled) map to environment variables by Quarkus's standard convention: uppercase, - → _, prefixed KC_. Verify current values against Keycloak's own docs before generating (https://github.com/keycloak/keycloak/blob/main/docs/guides/observability/tracing.adoc, https://www.keycloak.org/server/logging) — Keycloak's own config surface has already renamed properties within its lifecycle (see the deprecation note below), so treat this table as "verified as of this writing," not permanently pinned.

All three signals share one endpoint. --telemetry-endpoint / KC_TELEMETRY_ENDPOINT is "available only when any of available OpenTelemetry components (Logs, Metrics, Traces) is turned on," and --tracing-endpoint "is inherited from the telemetry-endpoint option" when not given (confirmed against Keycloak's own docs, quay.io/keycloak/keycloak:26.7.0 start --help-all, #196). Propose KC_TELEMETRY_ENDPOINT, not KC_TRACING_ENDPOINT, as the endpoint variable — setting only KC_TRACING_ENDPOINT means enabling OTLP logs or metrics later silently falls back to localhost:4317 a second time, unset. Only propose KC_TRACING_ENDPOINT directly when traces genuinely need to go somewhere DIFFERENT from logs/metrics, a real but unusual case — say so explicitly when you do.

Tracing (default OTLP protocol is gRPC, default endpoint http://localhost:4317 — same default this plugin uses elsewhere, so a target already running a collector on the plugin's standard port needs no endpoint override):

Tracing exports credentials: scrub before enabling (#197)

Keycloak's HTTP server spans record url.query verbatim, and Keycloak puts live credentials in query strings. The semantic conventions make url.query Conditionally Required on HTTP server spans and only say that sensitive content "SHOULD be scrubbed when instrumentations can identify it" (checked against semantic-conventions v1.44.0, docs/http/http-spans.md); an instrumentation cannot identify an application's own credential keys, and Keycloak's are not on the spec's default redaction list. Reported and reproduced in #197 with quay.io/keycloak/keycloak:26.7.0 exporting to otelcol-contrib 0.164.0:

So applying KC_TRACING_ENABLED=true as proposed puts replayable credentials into the trace backend, readable by everyone with trace access. Treat the scrub as a precondition of the diff, not an optional extra:

• It must be live on the receiving Collector before tracing is switched on. If that Collector is owned elsewhere (another team, a managed gateway), the env-var diff must not be applied until it is. Say this in the report; do not leave it implied.
• The scrub, scoped to this service by its service.name so other services' query strings are untouched (checked against otelcol-contrib 0.164.0: this service's spans lose both attributes, other services' keep them):

  processors:
    transform/keycloak-scrub:
      error_mode: ignore
      trace_statements:
        - context: span
          statements:
            - delete_key(attributes, "url.query") where resource.attributes["service.name"] == "<service.name>"
            - delete_key(attributes, "url.full")  where resource.attributes["service.name"] == "<service.name>"

  Add transform/keycloak-scrub to the traces pipeline between transform and batch (memory_limiter stays first). Prefer deleting over redacting by key (key=, code=, session_state=): a deny-list of keys misses the next one Keycloak adds, and the path already says what the request was.
• Already enabled? Then the exposure is current, not hypothetical. Lead the report with it even when nothing else needs proposing.
• Volume is a choice, not a silent default. The reporter measured about 1,500 spans in two minutes on an idle dev instance at the default ratio of 1.0, most of them internal and database spans. Offer KC_TRACING_SAMPLER_RATIO (or tail sampling at a gateway) as a decision for the user, and do not add it to the diff.

Logging — Keycloak's console handler logs unstructured plain text by default:

Metrics — KC_METRICS_ENABLED=true (build-time metrics-enabled) is the on/off switch; if already true, that is not a finding — do not propose re-adding it.

Native OTLP logs/metrics (Preview, #196) — Keycloak 26 can ALSO export logs and metrics directly over OTLP, not just to stdout/Prometheus. Neither is a finding when the target already has KC_LOG_CONSOLE_OUTPUT=json and/or KC_METRICS_ENABLED=true — those are a defensible, already-working setup — but mention the OTLP path exists as an option next to them, not silently: it gives logs/metrics the same service.name / resource attributes as traces, which a stdout tail or a Prometheus scrape does not carry. Only propose actually ADDING these if the target has NEITHER the existing path NOR the OTLP path for that signal.

Diff format per manifest type

Propose additions in the syntax of whatever service.deployment.configFiles actually contains — never assume one shape:

• Kubernetes Deployment/StatefulSet manifest, or Helm values.yaml: an env: list entry per variable (- name: KC_TRACING_ENABLED\n value: "true"), inserted into the existing container's env: block — read the file first to match its existing indentation and quoting style exactly, the same "extend, never clobber" discipline instrumentation-gen applies to a pre-existing instrumentation.ts.
• docker-compose.yml: an environment: map entry (KC_TRACING_ENABLED: "true", or the list form - KC_TRACING_ENABLED=true — match whichever form the file already uses).
• Dockerfile: an ENV KC_TRACING_ENABLED=true line, only when the image is built from this Dockerfile rather than pulled as-is — a FROM quay.io/keycloak/keycloak with no further customization has nowhere in the Dockerfile for this to usefully live; say so and point at the orchestration manifest instead.

Always show a unified diff (--- a/<path> / +++ b/<path>, @@ hunk headers) against the actual file content you read, never a bare "add these lines" list divorced from real context — the reader needs to see exactly where it goes and what it neighbors.

What this is not

/otel-remediate (v1) only prints the proposed diff — it never writes. Unlike a generated SDK bootstrap file (which this plugin owns and can safely regenerate under write-guard), a Kubernetes Deployment manifest or docker-compose file is infrastructure the plugin does not own and was not the one to create; write-guard's ownership-marker contract doesn't apply to it, and a wrong automated edit here has a materially higher blast radius (a live cluster resource) than a wrong edit to a bootstrap file the plugin generated in the first place. Print-only is not a missing feature to add later casually — treat "should this write automatically" as its own deliberate decision, not a default to slide into.