openshift · wgabor0427 · Apr 27, 2026
diff --git a/modules/ero-trust-manager-server-agent-telemetry.adoc b/modules/ero-trust-manager-server-agent-telemetry.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zer-trust-manager-features.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-server-agent-telemetry_{context}"]
+= SPIRE Server and Agent telemetry
+
+[role="_abstract"]
+Use the SPIRE Controller Manager to register workloads by using custom resource definitions (CRDs). The manager monitors pods and CRDs for changes and triggers a reconciliation process. This process creates, updates, or deletes SPIRE Server entries to help ensure they match your configuration.
diff --git a/modules/zero-trust-manager-about-controller-manager.adoc b/modules/zero-trust-manager-about-controller-manager.adoc
@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zer-trust-manager-features.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-about-controller-manager_{context}"]
+= SPIRE Controller Manager
+
+[role="_abstract"]
+Use the SPIRE Controller Manager to automate workload registration with custom resource definitions (CRDs). The manager monitors pods and CRDs to create, update, or delete entries on the SPIRE Server. This process helps ensure that your SPIRE entries accurately reflect your active resources.
+
+The SPIRE Controller Manager is designed to be deployed on the same pod as the SPIRE Server. The manager communicates with the SPIRE Server API using a private UNIX Domain Socket within a shared volume.
diff --git a/modules/zero-trust-manager-about-csi-driver.adoc b/modules/zero-trust-manager-about-csi-driver.adoc
@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zer-trust-manager-features.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-about-csi-driver_{context}"]
+= SPIFFE CSI Driver
+
+[role="_abstract"]
+The SPIFFE Container Storage Interface (CSI) driver helps pods securely obtain their {svid-full} by delivering the Workload API socket. By using Kubernetes ephemeral inline volumes, the driver simplifies how applications request temporary storage for identity management.
+
+When the pod starts, the Kubelet calls the SPIFFE CSI driver to provision and mount a volume into the pod's containers. The SPIFFE CSI driver mounts a directory that contains the SPIFFE Workload API into the pod. Applications in the pod then communicate with the Workload API to obtain their SVIDs. The driver guarantees that each SVID is unique.
diff --git a/modules/zero-trust-manager-about-oidc-provider.adoc b/modules/zero-trust-manager-about-oidc-provider.adoc
@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zer-trust-manager-features.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-about-oidc-provider_{context}"]
+= SPIRE OpenID Connect Discovery Provider
+
+[role="_abstract"]
+Use the SPIRE OpenID Connect (OIDC) Discovery Provider to integrate SPIRE workload identities with OIDC-compliant systems. This component exposes endpoints for token verification. It helps ensure compatibility between SPIRE-issued credentials and external APIs requiring standard OIDC tokens.
+
+While SPIRE primarily issues identities for workloads, additional workload-related claims can be embedded into JWT-SVIDs through the configuration of SPIRE, which these claims to be included in the token and verified by OIDC-compliant clients.
diff --git a/modules/zero-trust-manager-oidc-config.adoc b/modules/zero-trust-manager-oidc-config.adoc
@@ -4,9 +4,11 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="zero-trust-manager-oidc-config_{context}"]
+
 = Deploying the SPIRE OpenID Connect Discovery Provider
 
-You can configure the `SpireOIDCDiscoveryProvider` custom resource (CR) to deploy and configure the SPIRE OpenID Connect (OIDC) Discovery Provider.
+[role="_abstract"]
+Deploy the SPIRE OpenID Connect (OIDC) Discovery Provider by configuring the `SpireOIDCDiscoveryProvider` CR. This allows you to define the trust domain and JSON web token (JWT) issuer for your cluster.
 
 .Prerequisites
 
@@ -24,18 +26,36 @@ You can configure the `SpireOIDCDiscoveryProvider` custom resource (CR) to deplo
 +
 [source,yaml]
 ----
-apiVersion: operator.openshift.io/v1alpha1
+aapiVersion: operator.openshift.io/v1alpha1
 kind: SpireOIDCDiscoveryProvider
 metadata:
-  name: cluster
+ name: cluster
 spec:
-  trustDomain: <trust_domain> #<1>
-  agentSocketName: 'spire-agent.sock' #<2>
-  jwtIssuer: <jwt_issuer_domain> #<3>
+  logLevel: "info"
+  logFormat: "text"
+  csiDriverName: "csi.spiffe.io"
+  jwtIssuer: "https://oidc-discovery.apps.cluster.example.com"
+  replicaCount: 1
+  managedRoute: "true"
+  externalSecretRef: ""
 ----
-<1> The trust domain to be used for the SPIFFE identifiers.
-<2> The name of the SPIRE agent unix socket.
-<3> The JSON Web Token (JWT) issuer domain. The default value is set to the value specified in `oidc-discovery.$trustDomain`.
+where:
+
+`metadata.name`:: Specifies that the value must be `cluster`.
+
+`spec.logLevel`:: Specifies the logging level for the SPIRE Server. The valid options are `debug`, `info`, `warn`, and `error`.
+
+`spec.logFormat`:: Specifies the logging format for the SPIRE Server. The valid options are `text` and `json`.
+
+`spec.csiDriverName`:: Specifies the name of the CSI driver to use for mounting the Workload API socket. This must match the `SpiffeCSIDriver.spec.pluginName` value for the OIDC provider to access SPIFFE identities. Must be a valid DNS subdomain format (for example, `csi.spiffe.io`) with a maximum length of 127 characters.
+
+`spec.jwtIssuer`:: Specifies the JWT issuer URL. Must be a valid HTTPS or HTTP URL with a maximum length of 512 characters. This value must match the `SpireServer.spec.jwtIssuer` value.
+
+`spec.replicaCount`:: Specifies the number of replicas for the OIDC Discovery Provider deployment. Must be between 1 and 5.
+
+`spec.managedRoute`:: Specifies  whether the Operator automatically creates an OpenShift route for the OIDC Discovery Provider endpoints. Set to `true` to have the Operator automatically create and maintain an OpenShift route for OIDC discovery endpoints (`*.apps.`). Set to `false` for administrators to manually configure routes or ingress.
+
+`spec.ternalSecretRef`:: Specifies a reference to an externally managed secret that contains the TLS certificate for the OIDC Discovery Provider route host. Must be a valid Kubernetes secret reference name with a maximum length of 253 characters. This field is optional.
 
 .. Apply the configuration by running the following command:
 +

diff --git a/modules/zero-trust-manager-server-agent-telemetry.adoc b/modules/zero-trust-manager-server-agent-telemetry.adoc
@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zer-trust-manager-features.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-server-agent-telemetry_{context}"]
+= SPIRE Server and Agent telemetry
+
+[role="_abstract"]
+Use the SPIRE Controller Manager to register workloads by using custom resource definitions (CRDs). The manager monitors pods and CRDs for changes and triggers a reconciliation process. This process creates, updates, or deletes SPIRE Server entries to help ensure they match your configuration.
diff --git a/modules/zero-trust-manager-spiffe-csidriver-config.adoc b/modules/zero-trust-manager-spiffe-csidriver-config.adoc
@@ -6,7 +6,8 @@
 [id="zero-trust-manager-spire-csidriver-config_{context}"]
 = Deploying the SPIFFE Container Storage Interface driver
 
-You can configure the `SpiffeCSIDriver` custom resource (CR) to deploy and configure a SPIRE agent.
+[role="_abstract"]
+Configure the Container Storage Interface (CSI) driver using the `SpiffeCSIDriver` CR. This configuration mounts SPIFFE sockets directly into workload pods, which allows your applications to access the SPIFFE Workload API securely.
 
 .Prerequisites
 
@@ -27,11 +28,18 @@ You can configure the `SpiffeCSIDriver` custom resource (CR) to deploy and confi
 apiVersion: operator.openshift.io/v1alpha1
 kind: SpiffeCSIDriver
 metadata:
-  name: cluster
+ name: cluster
 spec:
-  agentSocketPath: '/run/spire/agent-sockets/spire-agent.sock' #<1>
+  agentSocketPath: "/run/spire/agent-sockets"
+  pluginName: "csi.spiffe.io"
 ----
-<1> The UNIX socket path to the SPIRE agent.
+where:
+
+`metadata.name`:: Specifies that the name must be `cluster`.
+
+`spec.agentSocketPath`:: Specifies the path to the directory containing the SPIRE agent's Workload API socket. This directory is bind-mounted into workload containers by the CSI driver. The directory is shared between the SPIRE agent and CSI driver via a `hostPath` volume. Must be an absolute path with a maximum length of 256 characters. This value must match `SpireAgent.spec.socketPath` for workloads to access the socket.
+
+`spec.pluginName`:: Specifies the name of the CSI plugin. This sets the CSI driver name that is deployed to the cluster and used in `VolumeMount` configurations. Must match the driver name referenced in the workload pods. Must be a valid domain name format (for example, `csi.spiffe.io`) with a maximum length of 127 characters.
 
 .. Apply the configuration by running the following command:
 +
@@ -42,7 +50,7 @@ $ oc apply -f SpiffeCSIDriver.yaml
 
 .Verification
 
-. Verify that the daemon set of the SPIFFE CSI driver is ready and available by running the following command:
+* Verify that the daemon set of the SPIFFE CSI driver is ready and available by running the following command:
 +
 [source,terminal]
 ----
@@ -56,7 +64,7 @@ NAME                      DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   N
 spire-spiffe-csi-driver   3         3         3       3            3           <none>          114s
 ----
 
-. Verify that the status of SPIFFE Container Storage Interface (CSI) Driver pods is `Running` by running the following command:
+* Verify that the status of SPIFFE Container Storage Interface (CSI) Driver pods is `Running` by running the following command:
 +
 [source,terminal]
 ----

diff --git a/modules/zero-trust-manager-spire-agent-config.adoc b/modules/zero-trust-manager-spire-agent-config.adoc
@@ -4,9 +4,11 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="zero-trust-manager-spire-agent-config_{context}"]
-= Deploying the SPIRE agent
+= Deploying the SPIRE Agent
+
+[role="_abstract"]
+Use the `SpireAgent` custom resource to configure the SPIRE Agent `DaemonSet` on your nodes. This defines how the agent verifies workloads and manages identity attestation across your {product-title} cluster.
 
-You can configure the `SpireAgent` custom resource (CR) to deploy and configure a SPIRE agent.
 
 .Prerequisites
 
@@ -27,22 +29,45 @@ You can configure the `SpireAgent` custom resource (CR) to deploy and configure
 apiVersion: operator.openshift.io/v1alpha1
 kind: SpireAgent
 metadata:
-  name: cluster
+ name: cluster
 spec:
-  trustDomain: <trust_domain> #<1>
-  clusterName: <cluster_name> #<2>
+  socketPath: "/run/spire/agent-sockets"
+  logLevel: "info"
+  logFormat: "text"
   nodeAttestor:
-    k8sPSATEnabled: "true" #<3>
+    k8sPSATEnabled: "true"
   workloadAttestors:
-    k8sEnabled: "true" #<4>
+    k8sEnabled: "true"
     workloadAttestorsVerification:
-      type: "auto" #<5>
+      type: "auto"
+      hostCertBasePath: "/etc/kubernetes"
+      hostCertFileName: "kubelet-ca.crt"
+    disableContainerSelectors: "false"
+    useNewContainerLocator: "true"
 ----
-<1> The trust domain to be used for the SPIFFE identifiers.
-<2> The name of your cluster.
-<3> Enable or disable the projected service account token (PSAT) Kubernetes node attestor. The valid options are `true` and `false`.
-<4> Enable or disable the Kubernetes workload attestor. The valid options are `true` and `false`.
-<5> The type of verification to be done against kubelet. Valid options are `auto`, `hostCert`, `apiServerCA`, `skip`. The `auto` option initially attempts to use `hostCert`, and then falls back to `apiServerCA`.
+where:
+
+`metadata.name`:: Specifies that the value must be `cluster`.
+
+`spec.socketPath`:: Specifies the directory on the host where the SPIRE agent socket is created. This directory is shared with the SPIFFE CSI driver via the `hostPath` volume. Must match the `SpiffeCSIDriver.spec.agentSocketPath` for workloads to access the socket. Must be an absolute path with a maximum length of 256 characters.
+
+`spec.logLevel`:: Specifies the logging level for the SPIRE Server. The valid options are `debug`, `info`, `warn`, and `error`.
+
+`spec.logFormat`:: Specifies the logging format for the SPIRE Server. The valid options are `text` and `json`.
+
+`spec.nodeAttestor.k8sPSATEnabled`:: Specifies whether Kubernetes Projected Service Account Token (PSAT) node attestation is enabled. When enabled, the SPIRE agent uses K8s PSATs to prove its identity to the SPIRE server during node attestation. The valid options are `true` and `false`.
+
+`spec.workloadAttestors.k8sEnabled`:: Specifies whether the Kubernetes workload attestor is enabled. When enabled, the SPIRE agent can verify workload identities using Kubernetes pod information and service account tokens. The valid options are `true` and `false`.
+
+`spec.workloadAttestors.workloadAttestorsVerification.type`:: Specifies the kubelet certificate verification mode. The valid options are `auto`, `hostCert`, and `skip`.
+
+`spec.workloadAttestors.workloadAttestorsVerification.hostCertBasePath`:: Specifies the directory containing the kubelet CA certificate. Required when type is `hostCert`. Optional when type is `auto` (defaults to /etc/kubernetes if not specified).
+
+`spec.workloadAttestors.workloadAttestorsVerification.hostCertFileName`:: Specifies the file name for the kubelet's CA certificate. When combined with `hostCertBasePath`, forms the full path. Required when type is `hostCert`. Optional when type is `auto`. Defaults to `kubelet-ca.crt` if not specified.
+
+`spec.workloadAttestors.disableContainerSelectors`:: Specifies whether to disable container selectors in the Kubernetes workload attestor. Set to `true` if using `holdApplicationUntilProxyStarts` in Istio. The valid options are `true` and `false`.
+
+`spec.workloadAttestors.useNewContainerLocator`:: Specifies enabling the new container locator algorithm that has support for cgroups v2. The valid options are `true` and `false`.
 
 .. Apply the configuration by running the following command:
 +
@@ -53,7 +78,7 @@ $ oc apply -f SpireAgent.yaml
 
 .Verification
 
-. Verify that the daemon set of the SPIRE agent is ready and available by running the following command
+* Verify that the daemon set of the SPIRE Agent is ready and available by running the following command:
 +
 [source,terminal]
 ----
@@ -67,7 +92,7 @@ NAME          DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR
 spire-agent   3         3         3       3            3           <none>          10m
 ----
 
-. Verify that the status of SPIRE agent pods is `Running` by running the following command:
+* Verify that the status of SPIRE Agent pods is `Running` by running the following command:
 +
 [source,terminal]
 ----