From 2be29d7728b2efad7f4a2b17f930d669d68f491f Mon Sep 17 00:00:00 2001 From: William Gabor Date: Fri, 25 Jul 2025 16:51:47 -0400 Subject: [PATCH] OSDOCS-15490 updated cert manager module --- .../zero-trust-manager-cert-manager-crd.adoc | 61 +++++++++++++++++++ ...nager-cert-manager-upstream-authority.adoc | 11 ++++ ...-trust-manager-configure-cert-manager.adoc | 18 ++++++ .../zero-trust-manager-configure-issuer.adoc | 45 ++++++++++++++ 4 files changed, 135 insertions(+) create mode 100644 modules/zero-trust-manager-cert-manager-crd.adoc create mode 100644 modules/zero-trust-manager-cert-manager-upstream-authority.adoc create mode 100644 modules/zero-trust-manager-configure-cert-manager.adoc create mode 100644 modules/zero-trust-manager-configure-issuer.adoc diff --git a/modules/zero-trust-manager-cert-manager-crd.adoc b/modules/zero-trust-manager-cert-manager-crd.adoc new file mode 100644 index 000000000000..193ad149570b --- /dev/null +++ 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 +---- + +. 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 -n +---- \ No newline at end of file diff --git a/modules/zero-trust-manager-cert-manager-upstream-authority.adoc b/modules/zero-trust-manager-cert-manager-upstream-authority.adoc new file mode 100644 index 000000000000..990be4adbc93 --- /dev/null +++ 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. \ No newline at end of file diff --git a/modules/zero-trust-manager-configure-cert-manager.adoc b/modules/zero-trust-manager-configure-cert-manager.adoc new file mode 100644 index 000000000000..4fa18700cf14 --- /dev/null +++ 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 new file mode 100644 index 000000000000..f7817060fe37 --- /dev/null +++ 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 +---- \ No newline at end of file