openshift · wgabor0427 · Jul 25, 2025
diff --git a/modules/zero-trust-manager-cert-manager-crd.adoc b/modules/zero-trust-manager-cert-manager-crd.adoc
@@ -0,0 +1,61 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="zero-trust-manager-cert-manager-crd_{context}"]
+= Configuring cert-manager plugin using the SPIRE server CRD
+
+To configure the cert-manager plugin using the SPIRE server Custom Resource Defnition (CRD), perform the following steps:
+
+.Procedure
+
+. Create a YAML file containing the configuration for the `SpireServer` resource, for example `spireserver.yaml`. The file includes the `spec` block and the `upstreamAuthority` block configured to use the `cert-manager` plugin.
++
+.Example `spireserver.yaml`
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1alpha1
+kind: SpireServer
+metadata:
+  name: cluster
+spec:
+  trustDomain: "example.org"
+  upstreamAuthority:
+    type: "cert-manager"
+    upstreamAuthorityCertManager:
+      issuerName: "ca-issuer" <1>
+      issuerKind: "ClusterIssuer" <2>
+      issuerGroup: "cert-manager.io" <3>
+      namespace: "zero-trust-workload-identity-manager" <4>
+      kubeConfigSecretName: "external-cluster-kubeconfig" <5>
+----
+<1> The name of the `cert-manager` Issuer or ClusterIssuer that signs the `certificateRequest`.
+<2> Set to `ClusterIssuer` if issuer is cluster-scoped. The default is `Issuer`.
+<3> The API group of the issuer. The default is `cert-manager.io`.
+<4> The namespace where the `CertificateRequest` is created. The default is `zero-trust-workload-identity-manager`.
+<5> The name of a Secret containing the `kubeconfig` to connect to the clsuter where `cert-manager` is running. If empy, an in-cluster configuration is used.
+
+. Apply the configuration by running the following command:
++
+[source, terminal]
+----
+$ oc apply -f spireserver.yaml
+----
+
+.Verification
+
+. Run the following command to list the `CertificateRequest` resources in the namespace where the SPIRE server creates them.
++
+[source, terminal]
+----
+$ oc get certificaterequests -n <namespace>
+----
+
+. Run the following command ot inspect a specific `CertificateRequest`. Review the `Status` section to confirm the certificate has been signed and that  the certificate data is present.
++
+[source, terminal]
+----
+$ oc describe certificaterequest <name-of-cert-request> -n <namespace>
+----
diff --git a/modules/zero-trust-manager-cert-manager-upstream-authority.adoc b/modules/zero-trust-manager-cert-manager-upstream-authority.adoc
@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-cert-manager-upstream-authority_{context}"]
+= About the cert-manager upstream authority plugin
+
+The cert-manager plugin for the SPIRE server is designed to automate the management of the SPIRE server's intermediate signing certificates by integrating with cert-manager in a Kubernetes environment. The cert-manager plugin enables the SPIRE server to dynamically request and receive intermediate signing certificates from cert-manager.
+
+When a SPIRE server needs a new certificate, the cert-manager plugin creates a `CertificateRequest` custom resource in the configured Kubernetes namespace which contains the Certificate Signing Request (CSR) generated by the SPIRE server. The cert-manager plugin processes the `CertificateRequest` and an associated `Issuer` signs the CSR. The signed intermediate certificate and the full Certificate Authority (CA) bundle are made available in the `CertificateRequest` status. These signed credentials are made available to the SPIRE server to be used as its upstream signing authority.
diff --git a/modules/zero-trust-manager-configure-cert-manager.adoc b/modules/zero-trust-manager-configure-cert-manager.adoc
@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-configure-cert-manager_{context}"]
+= Configuring the cert-manager plugin
+
+The cert-manager plugin for the SPIRE server is designed to automate the management of the SPIRE server intermediate signing certificates by integrating with cert-manager. The cert-manager plugin enables the SPIRE server to dynamically request and receive intermediate signing certificates from cert-manager.
+
+.Prerequisites
+
+* Access to a Kubernetes cluster where the SPIRE server runs.
+
+* cert-manager must be installed and running within the Kubernetes cluster. For more information about installing cert-manager, see link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html-single/security_and_compliance/index#cert-manager-operator-install[Installing the cert-manager Operator for Red{nbsp}Hat OpenShift].
+
+* A pre-configured cert-manager `Issuer` capable of signing intermediate Certificate Authority (CA) certificates.
+
diff --git a/modules/zero-trust-manager-configure-issuer.adoc b/modules/zero-trust-manager-configure-issuer.adoc
@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="zero-trust-manager-configure-issuer_{context}"]
+= Configuring the cert-manager issuer
+
+Before the cert-manager plugin can be configured, an `Issuer` needs to be created since the `Issuer` represents the CA and defines how certificates are issued. You create a cert-manager `Issuer` by performing the following steps:
+
+.Procedure
+
+. Generate the Transport Layer Security (TLS) secret by running the following command:
++
+[source,terminal]
+----
+$ oc create secret tls my-ca-key-pair-secret \
+  --cert=path/to/your/ca.crt \
+  --key=path/to/your/ca.key \
+  --namespace=my-namespace
+----
+
+. Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`:
++
+.Example `ca-issuer.yaml`
++
+[source,yaml]
+----
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: my-ca-issuer
+  namespace: my-namespace
+spec:
+  ca:
+    secretName: my-ca-key-pair-secret <1>
+----
+<1> The name of the Kubernetes Secret that holds the `tls.cert` and `tls.key` files. This secret must exist before you create the `Issuer`.
+
+. Apply the configuration by running the following command:
++
+[source, terminal]
+----
+$ oc apply -f ca-issuer.yaml
+----