OSDOCS-19019 added assembly and modules for plugins

_topic_maps/_topic_map.yml

@@ -1330,6 +1330,8 @@ Topics:
     File: zero-trust-manager-spire-federation
   - Name: Enabling create-only mode for the Zero Trust Workload Identity Manager
     File: zero-trust-manager-reconciliation
+  - Name: SPIRE UpstreamAuthority plugins for Zero Trust Workload Identity Manager
+    File: zero-trust-manager-plugins
   - Name: Monitoring Zero Trust Workload Identity Manager
     File: zero-trust-manager-monitoring
   - Name: Uninstalling the Zero Trust Workload Identity Manager

modules/zero-trust-manager-config-cert-manager.adoc

@@ -0,0 +1,74 @@
+// Module included in the following assemblies:
+//
+// * security/spire/cert-manager-upstream-authority-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="zero-trust-manager-config-cert-manager_{context}"]
+= Configuring the cert-manager upstream authority plugin
+
+[role="_abstract"]
+To enable SPIRE Server to automatically obtain intermediate signing certificates from cert-manager, configure the cert-manager upstream authority plugin. This procedure adds the plugin configuration to the SPIRE Server configuration file and restarts the server to apply the changes.
+
+.Procedure
+
+. Open the SPIRE Server configuration file by running the following command:
++
+[source,terminal]
+----
+$ vi /etc/spire/server/server.conf
+----
+
+. Create the `UpstreamAuthority` configuration block for the cert-manager plugin by running the following command:
++
+[source,hcl]
+----
+UpstreamAuthority "cert-manager" {
+    plugin_data {
+        issuer_name = "spire-ca"
+        issuer_kind = "Issuer"
+        issuer_group = "cert-manager.io"
+        namespace = "sandbox"
+        kube_config_file = "/etc/kubernetes/kubeconfig"
+    }
+}
+----
++
+where:
+
+`UpstreamAuthority.plugin_data.issuer_name`:: Specifies the name of your cert-manager issuer.
+
+`UpstreamAuthority.plugin_data.namespace`:: Specifies the namespace where `CertificateRequests` are created.
+
+`UpstreamAuthority.plugin_data.issuer_kind`:: Optional. Specifies the issuer type. The default value is `Issuer`:
+
+`UpstreamAuthority.plugin_data.issuer_group`:: Optional. Specifies the issuer group. The default value is `cert-manager.io`
+
+`UpstreamAuthority.plugin_data.kube_config_file`:: Optional. Specifies the issuer type. The default value is `Issuer`:
+
+. Restart the SPIRE Server to apply the changes by running the following command:
++
+[source,terminal]
+----
+$ systemctl restart spire-server
+----
++
+Or, if running in {product-title} run the following command:
++
+[source,terminal]
+----
+$ oc rollout restart deployment/spire-server -n sandbox
+----
+
+. Verify that the SPIRE Server started successfully by running the following command:
++
+[source,terminal]
+----
+$ systemctl status spire-server
+----
++
+Or, if running in {product-title} run the following command :
++
+[source,terminal]
+----
+$ oc logs -n sandbox deployment/spire-server
+----

modules/zero-trust-manager-plugins-cert-manager-about.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// * security/spire/cert-manager-upstream-authority-plugin.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-plugins-cert-manager-about_{context}"]
+= About the cert-manager upstream authority plugin
+
+[role="_abstract"]
+To centralize certificate management and leverage your existing organizational PKI infrastructure through cert-manager, you can use the cert-manager upstream authority plugin. This plugin connects SPIRE Server to a cert-manager instance for automated intermediate certificate provisioning.
+
+Use the cert-manager upstream authority plugin to automate intermediate certificate provisioning for SPIRE Server, centralizing certificate management and enforcing organizational policies.
+
+When you configure this plugin, SPIRE Server creates a `CertificateRequest` resource in the cluster. The cert-manager issuer processes the request and signs the certificate. After the issuer signs the request, SPIRE retrieves the intermediate certificate and CA bundle to use for signing workload identities.
+
+[id="cert-manager-plugin-workflow_{context}"]
+== How the cert-manager plugin works
+
+The cert-manager upstream authority plugin integrates SPIRE Server with cert-manager using the following workflow:
+
+. SPIRE Server generates a certificate signing request (CSR) for an intermediate signing certificate.
+
+. The plugin creates a `CertificateRequest` custom resource in the configured namespace.
+
+. The `CertificateRequest` references the specified issuer by name, kind, and group.
+
+. The cert-manager issuer processes the request and signs the certificate.
+
+. SPIRE Server retrieves the signed certificate and CA bundle from the `CertificateRequest` resource.
+
+. SPIRE Server uses the intermediate certificate to sign SPIFFE identities for workloads.
+
+[id="cert-manager-plugin-requirements_{context}"]
+== Requirements and considerations
+
+Before using the cert-manager upstream authority plugin, consider the following requirements:
+
+Cluster access:: The plugin requires access to a Kubernetes or OpenShift cluster running cert-manager. The SPIRE Server must be able to communicate with the Kubernetes API server.
+
+Issuer support:: Only issuers that support providing signing certificates are compatible with this plugin. The issuer must be capable of signing certificate requests for intermediate CA certificates.
+
+Permissions:: The Kubernetes client used by SPIRE Server must have permissions to create `CertificateRequest` resources in the configured namespace. The identity of this client can affect the approval flow if you are using a custom approver with cert-manager.
+
+[id="cert-manager-plugin-configuration-options_{context}"]
+== Configuration options
+
+The cert-manager upstream authority plugin supports the following configuration options:
+
+Namespace:: Specifies the namespace where `CertificateRequest` resources are created. This is a required parameter.
+
+Issuer reference:: Identifies the cert-manager issuer that signs the certificate requests. You must specify the issuer name. Optionally, you can specify the issuer kind (defaults to `Issuer`) and issuer group (defaults to `cert-manager.io`).
+
+Kubernetes configuration:: Specifies how SPIRE Server connects to the Kubernetes cluster. You can provide a path to a kubeconfig file, or omit this parameter to use in-cluster configuration when SPIRE Server runs as a pod in the cluster.
+
+[id="cert-manager-plugin-deployment-modes_{context}"]
+== Deployment modes
+
+You can deploy SPIRE Server with the cert-manager plugin in two configurations:
+
+In-cluster deployment:: When SPIRE Server runs as a pod in the same cluster as cert-manager, you can use in-cluster configuration. In this mode, SPIRE Server uses the service account token mounted in the pod to authenticate to the Kubernetes API. You do not need to specify a kubeconfig file.
+
+External deployment:: When SPIRE Server runs outside the cluster, you must provide a kubeconfig file that contains credentials for authenticating to the Kubernetes API. The kubeconfig must reference a service account or user with the necessary permissions to create `CertificateRequest` resources.

modules/zero-trust-manager-plugins-overview.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * security/spire/spire-upstream-authority-plugins.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="zero-trust-manager-plugins-overview_{context}"]
+= Configuring SPIRE UpstreamAuthority plugins
+
+[role="_abstract"]
+To integrate SPIRE Server with your existing certificate management infrastructure and select the appropriate upstream authority for your environment, review the available UpstreamAuthority plugins. SPIRE supports cert-manager and HashiCorp Vault plugins, each designed for specific certificate management scenarios.
+
+You can configure SPIRE Server to use one of the following UpstreamAuthority plugins:
+
+*cert-manager UpstreamAuthority plugin*:: Integrates SPIRE with cert-manager running in Kubernetes or {product-title} clusters. The cert-manager instance can use various issuer types to provide signing certificates for SPIRE intermediate CAs.
+
+*Vault UpstreamAuthority plugin*:: Integrates SPIRE with the HashiCorp Vault PKI Engine. This plugin supports multiple Vault authentication methods and enables SPIRE to leverage Vault's security features for certificate management.
+
+Choose the plugin that matches your certificate management infrastructure.

modules/zero-trust-manager-preparing-plugin-use.adoc

@@ -0,0 +1,128 @@
+// Module included in the following assemblies:
+//
+// * security/spire/cert-manager-upstream-authority-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="zero-trust-manager-preparing-plugin-use_{context}"]
+= Preparing to use the cert-manager upstream authority plugin
+
+You can configure SPIRE Server to use the cert-manager upstream authority plugin to request intermediate signing certificates from a cert-manager instance running in Kubernetes.
+
+Prepare your cluster environment and configure required permissions so SPIRE Server can request certificates from cert-manager without manual intervention.
+
+.Prerequisites
+
+* A Kubernetes cluster running cert-manager.
+
+* An issuer that supports providing signing certificates.
+
+* Access to configure the SPIRE Server.
+
+.Procedure
+
+. Verify that cert-manager is running in your cluster by running the following command:
++
+[source,terminal]
+----
+$ oc get pods -n cert-manager
+----
++
+.Example output
+[source,terminal]
+----
+NAME                                       READY   STATUS    RESTARTS   AGE
+cert-manager-5d7f97b46d-8xxxx              1/1     Running   0          1d
+cert-manager-cainjector-69d885bf55-xxxxx   1/1     Running   0          1d
+cert-manager-webhook-54754dcdfd-xxxxx      1/1     Running   0          1d
+----
+
+. Verify that you have an appropriate issuer configured that supports signing certificates by running the following command:
++
+[source,terminal]
+----
+$ oc get issuer,clusterissuer -A
+----
++
+.Example output
+[source,terminal]
+----
+NAMESPACE   NAME                        READY   AGE
+sandbox     issuer.cert-manager.io/spire-ca   True    1d
+----
+
+. Identify or create a namespace where `CertificateRequests` are created by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace sandbox
+----
+
+. Configure the required permissions:
+.. Create a service account for the SPIRE Server by running the following command:
++
+[source,terminal]
+----
+$ oc create serviceaccount spire-server -n sandbox
+----
+
+.. Create a role with `create` permissions for `CertificateRequests` by running the following command:
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: spire-server-cert-manager
+  namespace: sandbox
+rules:
+- apiGroups: ["cert-manager.io"]
+  resources: ["certificaterequests"]
+  verbs: ["create", "get", "list", "watch"]
+----
+
+.. Apply the role by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f spire-server-role.yaml
+----
+
+.. Create a role binding to grant the service account the required permissions by running the following command:
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: spire-server-cert-manager
+  namespace: sandbox
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: spire-server-cert-manager
+subjects:
+- kind: ServiceAccount
+  name: spire-server
+  namespace: sandbox
+----
+
+.. Apply the role binding by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f spire-server-rolebinding.yaml
+----
+
+. Optional: If connecting from outside the cluster, extract the kubeconfig for the service account by running the following command:
++
+[source,terminal]
+----
+$ oc create token spire-server -n sandbox --duration=8760h > /etc/kubernetes/kubeconfig
+----
++
+Alternatively, create a complete kubeconfig file by running the following command:
++
+[source,terminal]
+----
+$ oc config view --minify --flatten > /etc/kubernetes/kubeconfig
+----

security/zero_trust_workload_identity_manager/zero-trust-manager-plugins.adoc

@@ -0,0 +1,22 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="zero-trust-manager-plugins"]
+= SPIRE UpstreamAuthority plugins for Zero Trust Workload Identity Manager 
+include::_attributes/common-attributes.adoc[]
+:context: zero-trust-manager-plugins
+
+toc::[]
+
+[role="_abstract"]
+To integrate SPIRE with your existing certificate management infrastructure and maintain SPIFFE identity standards, you can use UpstreamAuthority plugins. These plugins obtain intermediate signing certificates from external certificate authorities such as cert-manager or HashiCorp Vault.
+
+// Configuring SPIRE UpstreamAuthority plugins
+include::modules/zero-trust-manager-plugins-overview.adoc[leveloffset=+1]
+
+// About the cert-manager upstream authority plugin
+include::modules/zero-trust-manager-plugins-cert-manager-about.adoc[leveloffset=+1]
+
+// Preparing to use the cert-manager upstream authority plugin
+include::modules/zero-trust-manager-preparing-plugin-use.adoc[leveloffset=+1]
+
+// Preparing to use the cert-manager upstream authority plugin
+include::modules/zero-trust-manager-config-cert-manager.adoc[leveloffset=+1]