Feat: [spec] mTLS transport security for agent communication (003)

[varshaprasad96]

Summary

• Adds spec-driven development artifacts for mTLS transport security (spec 003)
• Covers two communication paths: controller-to-agent and agent-to-agent mTLS
• SPIRE is the sole certificate provider; Istio is explicitly out of scope
• mTLS defaults to permissive (enabled by default, opt-out with mTLSMode: disabled)
• Authbridge mTLS is already implemented — remaining work is primarily operator-side

Artifacts

File	Purpose
specs/003-mtls-transport-security/spec.md	Feature specification with user stories, requirements, acceptance scenarios
specs/003-mtls-transport-security/plan.md	Implementation plan with constitution check and project structure
specs/003-mtls-transport-security/research.md	Research decisions (config schema, SpiffeFetcher, MTLSReady condition)
specs/003-mtls-transport-security/data-model.md	Entity changes, condition states, state transitions
specs/003-mtls-transport-security/tasks.md	24 implementation tasks across 8 phases
specs/003-mtls-transport-security/contracts/	Operator-to-authbridge mTLS config contract
specs/003-mtls-transport-security/brainstorm.md	Design exploration and clarification answers

Key Decisions

• SPIRE only — no Istio dependency
• mTLS enabled by default — permissive mode, operators opt out with mTLSMode: disabled
• Fail clearly — MTLSReady=False condition when SPIRE is unavailable
• Controller uses go-spiffe SDK directly (SpiffeFetcher as default)
• spiffe-helper for data-plane certificates (file-based, sidecar-agnostic)
• JWS signing deprecated — flags default to false with warnings

References

• ADR: ODH-ADR-AgentOps-0002
• Jira: RHAIENG-4944
• Parent: RHAISTRAT-1599

Test plan

• Team reviews spec, plan, and task breakdown
• Validate assumptions about authbridge mTLS state on main
• Confirm ConfigMap schema matches authbridge expectations
• Agree on MVP scope (US1: agent-to-agent mTLS by default)

Signed-off-by: Varsha Prasad Narsing varshaprasad96@gmail.com
🤖 Generated with Claude Code

[varshaprasad96]

cc: @r3v5 @akram Can we review this, before moving to implementation

[r3v5]

lgtm thank you!

[r3v5]

This work was kicked off already, covers Istio service mesh with mTLS (L4) for pod-to-pod traffic encryption:

1. feat: create SharedTrust controller for cert-manager cacerts reconciliation #383
2. [kagenti-operator] Auto-label namespaces with istio-discovery=enabled when AgentRuntime CR is created #399
3. [RHAIENG-5467]

[cwiklik]

The DCO check is failing on this PR — one of the two commits is missing its Signed-off-by trailer:

• ❌ 3ba96e2 — spec: add mTLS transport security spec (003) — not signed off
• ✅ 3f4cae4 — spec: update tasks.md with codebase audit findings — signed off

To fix, sign off all commits on the branch and force-push:

git rebase --signoff main      # use origin/main or upstream/main if that is your base
git push --force-with-lease

The Signed-off-by: name/email must match the commit author. Once the missing sign-off is added, the DCO check will re-run and pass.

[rhuss]

Review Guide: mTLS Transport Security for Agent Communication

Generated: 2026-06-08 | Spec: specs/003-mtls-transport-security/spec.md

Why This Change

Agent-to-agent and controller-to-agent communication in kagenti currently runs over plaintext HTTP by default. While authbridge already has full mTLS support implemented (permissive/strict modes, SPIRE-based SVIDs, per-handshake cert rotation), the operator doesn't activate it by default. Operators must manually set flags and configure mTLS mode. This spec makes mTLS the default transport security, with clear error conditions when SPIRE is unavailable.

What Changes

1. mTLS enabled by default: mTLSMode defaults to permissive (was implicitly disabled). Agents communicate over mTLS automatically when SPIRE is deployed.
2. MTLSReady condition: New status condition on AgentRuntime showing whether mTLS infrastructure (SPIRE) is available, with actionable error messages when it's not.
3. Controller uses mTLS by default: --enable-verified-fetch and --enable-card-discovery flags flip to true. SpiffeFetcher becomes the default card fetcher.
4. JWS signing deprecation: Legacy signing flags (--require-a2a-signature, --signature-audit-mode, --enforce-network-policies) emit deprecation warnings.
5. ConfigMap mtls block: Operator injects mtls: mode: <value> into authbridge ConfigMap based on AgentRuntime spec.

No breaking changes. Existing deployments without SPIRE get a clear MTLSReady=False condition and can opt out with mTLSMode: disabled.

How It Works

The implementation leverages heavily what's already built:

• Authbridge (kagenti-extensions): mTLS is fully implemented across all proxy modes. No changes needed, only verification.
• Operator: The main work is (a) changing the mTLSMode kubebuilder default to permissive, (b) injecting the mtls: block into the authbridge ConfigMap, (c) adding MTLSReady condition logic, and (d) flipping flag defaults.
• SPIRE detection: The controller checks whether spiffe-helper volume mounts exist in the workload's pod template. If absent while mTLS is enabled, MTLSReady=False/SPIREUnavailable.
• Config hash: resolvedConfig.MTLSMode is already included in the config hash, so mTLSMode changes trigger rolling restarts automatically.

Of 24 tasks, 2 are already done ([DONE]), 1 is partial ([PARTIAL]), and the remaining 21 are new work, mostly focused on the operator side.

When It Applies

Applies when:

• Deploying agents in clusters with SPIRE
• Controller fetching agent cards from live workloads
• Setting or changing mTLSMode on AgentRuntime CRs
• Migrating from JWS signing to mTLS-based identity

Does not apply when:

• Using Istio service mesh for mTLS (explicitly out of scope, separate effort in #399)
• Working with user-supplied certificates or cert-manager (future iteration)
• Authbridge plugin changes (orthogonal)
• Cross-cluster agent federation (future work)

Key Decisions

1. SPIRE only, no Istio dependency: The spec explicitly scopes to SPIRE-based mTLS. Istio service mesh mTLS (L4, pod-to-pod) is a separate effort tracked in #399 and PR #383. These are complementary (SPIRE = application-layer identity, Istio = infrastructure-layer encryption), not competing.

2. Permissive as default, not strict: Accepts both TLS and plaintext inbound. This allows gradual rollout without breaking existing agents that haven't enabled SPIRE yet.

3. Controller uses go-spiffe SDK directly: SpiffeFetcher uses go-spiffe/v2 X509Source in-process, not file-based certificates. This is different from the data-plane approach (spiffe-helper sidecar writing PEM files).

4. Feature-gated via existing CRD field: No new CLI flag for mTLS enablement. The mTLSMode field on AgentRuntimeSpec is the control surface. --enable-verified-fetch is retained as a kill switch only.

5. JWS signing soft-deprecated: Flags default to false (already on main), warnings added. No code removal yet, just signaling the migration path.

Areas Needing Attention

• Overlap with Istio mTLS work: PR #383 (SharedTrust controller, already merged) and Issue #399 (Istio auto-labeling) introduce Istio-based mTLS at the infrastructure layer. This spec operates at the application layer (SPIRE). Reviewers should verify these don't conflict at the configuration level (e.g., what happens when both SPIRE mTLS and Istio mTLS are active on the same workload).

• ConfigMap schema contract: T005 (injecting mtls: block) and T020 (verifying authbridge expects this shape) are the critical integration point. If the authbridge config schema doesn't match what the operator generates, mTLS silently fails.

• MTLSReady condition gating Ready: T016 proposes that MTLSReady=False should affect the overall Ready condition. The exact behavior (block Ready entirely vs. add a warning) needs careful design, since it changes the controller's availability semantics.

• SPIRE detection heuristic: Using spiffe-helper volume mount presence as a proxy for "SPIRE is available" may not cover all deployment patterns (e.g., SPIRE with CSI driver instead of init container).

Open Questions

• How do SPIRE-based mTLS (this spec) and Istio-based mTLS (PR #383, Issue #399) coexist? Is double encryption acceptable, or should one disable when the other is active?
• Should MTLSReady=False block the overall Ready=True condition, or just add a warning?
• Does the SPIRE detection heuristic (spiffe-helper volume check) cover SPIRE CSI driver deployments?

Review Checklist

• Key decisions are justified (especially SPIRE-only vs Istio interaction)
• Scope matches the stated boundaries (no Istio, no user certs, no cross-cluster)
• Constitution compliance verified (all 5 principles addressed in plan.md)
• ConfigMap mtls: block schema matches authbridge expectations
• No conflict with existing SharedTrust controller (PR #383)
• Task reconciliation against main is accurate ([DONE]/[PARTIAL] markers)
• Success criteria are achievable and testable
• Deprecation warnings are clear and actionable

[varshaprasad96]

Using the following points for tracking based on #405 and team review:

• FR-009: hash-based restart → annotation-based restart (kagenti.io/mtls-mode)
• Remove ConfigMap mtls: block injection (T005, contracts/) — webhook handles this
• Add: controller sets kagenti.io/mtls-mode annotation on pod template
• Add: webhook reads mTLSMode from AgentRuntime CR, sets env var on authbridge container
• Clarify controller/webhook boundary for mTLS config delivery

[pdettori]

Solid spec-first approach. Architecture is sound — leveraging existing authbridge mTLS and adding operator-side wiring. The team has already identified the key pivot via #405 (annotation-based delivery via webhook instead of ConfigMap injection), which simplifies the operator's responsibility.

Main suggestion: update the spec artifacts to reflect the #405 decisions before merge, so the spec doesn't go stale on day one.

Areas reviewed: Architecture/design, scope boundaries, security model, task coherence
Commits: 4 commits, all signed-off ✓
CI: E2E failing (unrelated — spec-only PR), all other checks pass

[varshaprasad96]

Have updated based on aggregates made in #405. Are we good with getting the spec in?
cc: @r3v5 @pdettori @rh-dnagornuks