docs: add Fulcio KMS signer backend guide (SECURESIGN-4465)

[kdacosta0]

What changed

New guide docs/fulcio-kms.md — how to configure Fulcio with a KMS signing backend.

Why

KMS signer support is being added in #2184. Users need a guide covering supported providers, certificate chain preparation, Securesign CR example with auth, and type switching.

Depends on: #2184 (Fulcio KMS signer implementation)

REF: SECURESIGN-4465

[qodo-for-securesign]

PR Summary by Qodo

Document Fulcio KMS signer backend configuration

📝 Documentation 🕐 10-20 Minutes

AI Description

• Document supported KMS providers, URI formats, authentication, and Vault-specific requirements.
• Explain CA chain preparation and provide a complete Securesign KMS example.
• Add deployment verification, signing tests, rotation, and FIPS references.

Diagram

graph TD
  Admin["Cluster Admin"] --> CR["Securesign CR"] --> Operator["RHTAS Operator"] --> Fulcio["Fulcio Server"] --> KMS["External KMS"]
  Secret["CA Chain Secret"] --> Fulcio
  Cosign["Cosign Client"] --> Fulcio

Loading

High-Level Assessment

A single provider-neutral guide is the best fit because certificate preparation, Securesign configuration, and verification are shared across KMS backends. Splitting the material into provider-specific pages would duplicate most of the workflow; the provider table and focused GCP/Vault notes preserve the necessary distinctions concisely.

Files changed (1) +100 / -0

Documentation (1) +100 / -0

fulcio-kms.mdAdd Fulcio KMS signer configuration guide +100/-0

Add Fulcio KMS signer configuration guide

• Adds supported provider URI and authentication references, CA certificate-chain preparation requirements, and a complete AWS-backed Securesign example. Documents GCP secret mounting, deployment verification, end-to-end signing checks, and links to rotation and FIPS guidance.

docs/fulcio-kms.md

[qodo-for-securesign]

Code Review by Qodo

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

1. Unsupported KMS signer fields ✓ Resolved 🐞 Bug ≡ Correctness

Description

The guide instructs configuring spec.fulcio.signer.type: kms with signer.kms and signer.auth,
but the current Fulcio/Securesign API only supports signer.type=file and has no kms/auth
fields, so the example CR will be rejected by schema validation. Additionally, the operator
currently hard-codes Fulcio deployment args for --ca=fileca, so the documented KMS-specific args
check cannot succeed in this branch.

Code

docs/fulcio-kms.md[R46-49]

+    signer:
+      type: kms
+      kms:
+        keyResource: "awskms:///1234abcd-12ab-34cd-56ef-1234567890ab"

Relevance

●● Moderate

Guide may be intentionally ahead of implementation (#2184 dependency); docs/schema alignment likely
required before merge.

PR-#1485

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Fulcio signer API in this branch only allows type=file and exposes no kms/auth
configuration, while the controller currently deploys Fulcio with --ca=fileca; therefore the
guide’s KMS config and verification steps don’t work as documented.

api/v1/fulcio_types.go[42-55]
api/v1/fulcio_defaults.go[11-13]
internal/controller/fulcio/actions/deployment.go[136-147]

Agent prompt

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

### Issue description
`docs/fulcio-kms.md` documents a KMS signer configuration (`signer.type: kms`, `signer.kms`, `signer.auth`) that is not supported by the current `api/v1` Fulcio/Securesign schema and does not match the current Fulcio deployment args the operator generates.

### Issue Context
In this branch, Fulcio signer type is restricted to `file` and the deployment args are hard-coded to `--ca=fileca` with `--fileca-*` flags.

### Fix Focus Areas
- docs/fulcio-kms.md[39-86]
- api/v1/fulcio_types.go[42-55]
- internal/controller/fulcio/actions/deployment.go[136-147]

### What to change
- Update the guide to match the actual CRD fields and deployment flags available in this repo version, **or** explicitly gate the guide to the operator version/PR where KMS support is present and ensure the documented YAML matches that implementation exactly.
- Ensure the “Verify pod args” section reflects the real args produced by the operator for KMS mode (once implemented), not `fileca`.

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

---

2. AWS credentials secret missing 🐞 Bug ≡ Correctness ⭐ New

Description

The example references aws-credentials and its two keys, but the guide only creates the
certificate-chain Secret. Following these steps without separately guessing and provisioning that
Secret leaves the Fulcio pod with unresolved secretKeyRef dependencies and prevents it from
starting.

Code

docs/fulcio-kms.md[R53-55]

+            secretKeyRef:
+              name: aws-credentials
+              key: access-key-id

Relevance

●●● Strong

Missing referenced Secret is a concrete documentation omission that prevents the example deployment
from starting.

PR-#1495

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The manifest's authentication environment is propagated to the real Fulcio container, making both
SecretKeyRefs runtime dependencies, while the only Secret creation command in the guide creates
fulcio-kms-cert rather than aws-credentials.

docs/fulcio-kms.md[27-30]
docs/fulcio-kms.md[49-60]
internal/controller/fulcio/actions/deployment.go[98-105]

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 AWS example consumes an `aws-credentials` Secret that the setup procedure never creates.

## Issue Context
Document how to create or otherwise provision `aws-credentials` in the same namespace, with the `access-key-id` and `secret-access-key` keys used by the manifest, before applying the Securesign CR.

## Fix Focus Areas
- docs/fulcio-kms.md[27-30]
- docs/fulcio-kms.md[49-60]

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

---

3. Verification reads wrong container 🐞 Bug ≡ Correctness ⭐ New

Description

The verification JSONPath always reads containers[0], but the operator locates the managed
container by the name fulcio-server and pod extensions can alter container ordering. With a
sidecar at index zero, the command prints unrelated arguments and falsely indicates that the KMS
flags are missing.

Code

docs/fulcio-kms.md[88]

+oc get deployment fulcio-server -n <namespace> -o jsonpath='{.spec.template.spec.containers[0].args}'

Relevance

●●● Strong

Hard-coded container index makes verification unreliable with documented pod extensions and
sidecars.

PR-#2007

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide hard-codes container index zero, while deployment reconciliation applies user pod
extensions first and then finds or creates the Fulcio container by name before appending the KMS
arguments.

docs/fulcio-kms.md[86-90]
internal/controller/fulcio/actions/deployment.go[71-81]
internal/controller/fulcio/actions/deployment.go[372-386]

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 deployment verification command selects the first container rather than the operator-managed `fulcio-server` container, so it can inspect a sidecar's arguments.

## Issue Context
Pod extensions are applied before the operator ensures the named Fulcio container, and container order is not guaranteed. Use a JSONPath predicate selecting `.name == "fulcio-server"`.

## Fix Focus Areas
- docs/fulcio-kms.md[86-90]

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

---

4. OpenBao URI unsupported 🐞 Bug ≡ Correctness

Description

The guide documents openbao://... as a supported KMS provider URI, but the operator’s existing KMS
URI allowlists (CEL/XValidation) only recognize awskms://, gcpkms://, azurekms://, and
hashivault://. Users following the guide may supply a URI scheme the operator will reject as
invalid.

Code

docs/fulcio-kms.md[13]

+| OpenBao | `openbao://keyname` | `VAULT_ADDR` or `BAO_ADDR`, `VAULT_TOKEN` or `BAO_TOKEN` |

Relevance

●●● Strong

Team often accepts changes preventing user-facing config/docs drift vs validation/actual behavior;
this is a real mismatch risk.

PR-#1260
PR-#1484

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide explicitly recommends an openbao:// URI, but the repo’s KMS URI validation rules (used
for other KMS-backed components) only allow awskms://, gcpkms://, azurekms://, and
hashivault://, with no openbao:// option.

docs/fulcio-kms.md[7-15]
api/v1/rekor_types.go[100-113]
api/v1/timestampauthority_types.go[116-122]

Agent prompt

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

### Issue description
`docs/fulcio-kms.md` lists OpenBao as supported with an `openbao://...` URI scheme. Elsewhere in this repo, KMS URI validation allowlists only include `awskms://`, `gcpkms://`, `azurekms://`, and `hashivault://`.

### Issue Context
The operator already constrains KMS URIs via kubebuilder CEL/XValidation rules (see Rekor and TSA types). The doc should either:
- document only URI schemes that the operator accepts, or
- if OpenBao is intended to be supported as a distinct scheme, align the API validation/schema (and implementation) accordingly.

### Fix Focus Areas
- docs/fulcio-kms.md[7-15]

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

---

View medium (1)

5. Wrong condition JSONPath ✓ Resolved 🐞 Bug ≡ Correctness

Description

The guide’s verification command filters for a condition type named CertCondition, but the
controller sets the certificate condition type to FulcioCertAvailable. Running the documented
JSONPath will typically return an empty result even when certificate provisioning succeeded.

Code

docs/fulcio-kms.md[R115-118]

+Check that `CertCondition` is `True`:
+```bash
+oc get fulcio <name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="CertCondition")].status}'
+```

Relevance

●●● Strong

Docs correctness fix; wrong condition name makes verification command unusable, typically corrected
in-docs.

PR-#1485

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The docs query for condition type CertCondition, but the operator’s constant for the certificate
condition is FulcioCertAvailable, so the JSONPath filter does not match what the controller sets.

internal/controller/fulcio/actions/constants.go[5-18]

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 verification step queries `.status.conditions[?(@.type=="CertCondition")]`, but the actual condition type string is `FulcioCertAvailable`.

### Issue Context
The controller constant `CertCondition` is set to the literal string `FulcioCertAvailable` and is used when generating signer/cert conditions.

### Fix Focus Areas
- docs/fulcio-kms.md[113-118]
- internal/controller/fulcio/actions/constants.go[14-15]

### What to change
- Replace `CertCondition` in the JSONPath filter with `FulcioCertAvailable` (or document the exact user-facing condition type emitted by the operator).

ⓘ 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

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous reviews

Review updated until commit 9e5ad60

Results up to commit 73b29f1 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Unsupported KMS signer fields ✓ Resolved 🐞 Bug ≡ Correctness

Description

The guide instructs configuring spec.fulcio.signer.type: kms with signer.kms and signer.auth,
but the current Fulcio/Securesign API only supports signer.type=file and has no kms/auth
fields, so the example CR will be rejected by schema validation. Additionally, the operator
currently hard-codes Fulcio deployment args for --ca=fileca, so the documented KMS-specific args
check cannot succeed in this branch.

Code

docs/fulcio-kms.md[R46-49]

+    signer:
+      type: kms
+      kms:
+        keyResource: "awskms:///1234abcd-12ab-34cd-56ef-1234567890ab"

Relevance

●● Moderate

Guide may be intentionally ahead of implementation (#2184 dependency); docs/schema alignment likely
required before merge.

PR-#1485

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Fulcio signer API in this branch only allows type=file and exposes no kms/auth
configuration, while the controller currently deploys Fulcio with --ca=fileca; therefore the
guide’s KMS config and verification steps don’t work as documented.

api/v1/fulcio_types.go[42-55]
api/v1/fulcio_defaults.go[11-13]
internal/controller/fulcio/actions/deployment.go[136-147]

Agent prompt

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

### Issue description
`docs/fulcio-kms.md` documents a KMS signer configuration (`signer.type: kms`, `signer.kms`, `signer.auth`) that is not supported by the current `api/v1` Fulcio/Securesign schema and does not match the current Fulcio deployment args the operator generates.

### Issue Context
In this branch, Fulcio signer type is restricted to `file` and the deployment args are hard-coded to `--ca=fileca` with `--fileca-*` flags.

### Fix Focus Areas
- docs/fulcio-kms.md[39-86]
- api/v1/fulcio_types.go[42-55]
- internal/controller/fulcio/actions/deployment.go[136-147]

### What to change
- Update the guide to match the actual CRD fields and deployment flags available in this repo version, **or** explicitly gate the guide to the operator version/PR where KMS support is present and ensure the documented YAML matches that implementation exactly.
- Ensure the “Verify pod args” section reflects the real args produced by the operator for KMS mode (once implemented), not `fileca`.

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

---

2. Wrong condition JSONPath ✓ Resolved 🐞 Bug ≡ Correctness

Description

The guide’s verification command filters for a condition type named CertCondition, but the
controller sets the certificate condition type to FulcioCertAvailable. Running the documented
JSONPath will typically return an empty result even when certificate provisioning succeeded.

Code

docs/fulcio-kms.md[R115-118]

+Check that `CertCondition` is `True`:
+```bash
+oc get fulcio <name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="CertCondition")].status}'
+```

Relevance

●●● Strong

Docs correctness fix; wrong condition name makes verification command unusable, typically corrected
in-docs.

PR-#1485

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The docs query for condition type CertCondition, but the operator’s constant for the certificate
condition is FulcioCertAvailable, so the JSONPath filter does not match what the controller sets.

internal/controller/fulcio/actions/constants.go[5-18]

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 verification step queries `.status.conditions[?(@.type=="CertCondition")]`, but the actual condition type string is `FulcioCertAvailable`.

### Issue Context
The controller constant `CertCondition` is set to the literal string `FulcioCertAvailable` and is used when generating signer/cert conditions.

### Fix Focus Areas
- docs/fulcio-kms.md[113-118]
- internal/controller/fulcio/actions/constants.go[14-15]

### What to change
- Replace `CertCondition` in the JSONPath filter with `FulcioCertAvailable` (or document the exact user-facing condition type emitted by the operator).

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

---

Results up to commit e06889a ⚖️ Balanced

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. OpenBao URI unsupported 🐞 Bug ≡ Correctness

Description

The guide documents openbao://... as a supported KMS provider URI, but the operator’s existing KMS
URI allowlists (CEL/XValidation) only recognize awskms://, gcpkms://, azurekms://, and
hashivault://. Users following the guide may supply a URI scheme the operator will reject as
invalid.

Code

docs/fulcio-kms.md[13]

+| OpenBao | `openbao://keyname` | `VAULT_ADDR` or `BAO_ADDR`, `VAULT_TOKEN` or `BAO_TOKEN` |

Relevance

●●● Strong

Team often accepts changes preventing user-facing config/docs drift vs validation/actual behavior;
this is a real mismatch risk.

PR-#1260
PR-#1484

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide explicitly recommends an openbao:// URI, but the repo’s KMS URI validation rules (used
for other KMS-backed components) only allow awskms://, gcpkms://, azurekms://, and
hashivault://, with no openbao:// option.

docs/fulcio-kms.md[7-15]
api/v1/rekor_types.go[100-113]
api/v1/timestampauthority_types.go[116-122]

Agent prompt

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

### Issue description
`docs/fulcio-kms.md` lists OpenBao as supported with an `openbao://...` URI scheme. Elsewhere in this repo, KMS URI validation allowlists only include `awskms://`, `gcpkms://`, `azurekms://`, and `hashivault://`.

### Issue Context
The operator already constrains KMS URIs via kubebuilder CEL/XValidation rules (see Rekor and TSA types). The doc should either:
- document only URI schemes that the operator accepts, or
- if OpenBao is intended to be supported as a distinct scheme, align the API validation/schema (and implementation) accordingly.

### Fix Focus Areas
- docs/fulcio-kms.md[7-15]

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

---

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.72%. Comparing base (0356c18) to head (9e5ad60).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2187   +/-   ##
=======================================
  Coverage   60.72%   60.72%           
=======================================
  Files         299      299           
  Lines       17115    17115           
=======================================
  Hits        10393    10393           
  Misses       5716     5716           
  Partials     1006     1006           

Flag	Coverage Δ
e2e	72.92% <ø> (-0.11%)	⬇️
unit	40.58% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[qodo-for-securesign]

Code review by qodo was updated up to the latest commit e06889a

[qodo-for-securesign]

Code review by qodo was updated up to the latest commit 4d09151