Skip to content

Commit 029389a

Browse files
wgabor0427wgabor0427
committed
added config cert-manager module
1 parent d81bcab commit 029389a

File tree

6 files changed

+306
-0
lines changed

6 files changed

+306
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1330,6 +1330,8 @@ Topics:
13301330
File: zero-trust-manager-spire-federation
13311331
- Name: Enabling create-only mode for the Zero Trust Workload Identity Manager
13321332
File: zero-trust-manager-reconciliation
1333+
- Name: SPIRE UpstreamAuthority plugins for Zero Trust Workload Identity Manager
1334+
File: zero-trust-manager-plugins
13331335
- Name: Monitoring Zero Trust Workload Identity Manager
13341336
File: zero-trust-manager-monitoring
13351337
- Name: Uninstalling the Zero Trust Workload Identity Manager

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/spire/cert-manager-upstream-authority-plugin.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-config-cert-manager_{context}"]
7+
= Configuring the cert-manager upstream authority plugin
8+
9+
[role="_abstract"]
10+
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.
11+
12+
.Procedure
13+
14+
. Open the SPIRE Server configuration file by running the following command:
15+
+
16+
[source,terminal]
17+
----
18+
$ vi /etc/spire/server/server.conf
19+
----
20+
21+
. Create the `UpstreamAuthority` configuration block for the cert-manager plugin by running the following command:
22+
+
23+
[source,hcl]
24+
----
25+
UpstreamAuthority "cert-manager" {
26+
plugin_data {
27+
issuer_name = "spire-ca"
28+
issuer_kind = "Issuer"
29+
issuer_group = "cert-manager.io"
30+
namespace = "sandbox"
31+
kube_config_file = "/etc/kubernetes/kubeconfig"
32+
}
33+
}
34+
----
35+
+
36+
where:
37+
38+
`UpstreamAuthority.plugin_data.issuer_name`:: Specifies the name of your cert-manager issuer.
39+
40+
`UpstreamAuthority.plugin_data.namespace`:: Specifies the namespace where `CertificateRequests` are created.
41+
42+
`UpstreamAuthority.plugin_data.issuer_kind`:: Optional. Specifies the issuer type. The default value is `Issuer`:
43+
44+
`UpstreamAuthority.plugin_data.issuer_group`:: Optional. Specifies the issuer group. The default value is `cert-manager.io`
45+
46+
`UpstreamAuthority.plugin_data.kube_config_file`:: Optional. Specifies the issuer type. The default value is `Issuer`:
47+
48+
. Restart the SPIRE Server to apply the changes by running the following command:
49+
+
50+
[source,terminal]
51+
----
52+
$ systemctl restart spire-server
53+
----
54+
+
55+
Or, if running in {product-title} run the following command:
56+
+
57+
[source,terminal]
58+
----
59+
$ oc rollout restart deployment/spire-server -n sandbox
60+
----
61+
62+
. Verify that the SPIRE Server started successfully by running the following command:
63+
+
64+
[source,terminal]
65+
----
66+
$ systemctl status spire-server
67+
----
68+
+
69+
Or, if running in {product-title} run the following command :
70+
+
71+
[source,terminal]
72+
----
73+
$ oc logs -n sandbox deployment/spire-server
74+
----

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/spire/cert-manager-upstream-authority-plugin.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-plugins-cert-manager-about_{context}"]
7+
= About the cert-manager upstream authority plugin
8+
9+
[role="_abstract"]
10+
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.
11+
12+
Use the cert-manager upstream authority plugin to automate intermediate certificate provisioning for SPIRE Server, centralizing certificate management and enforcing organizational policies.
13+
14+
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.
15+
16+
[id="cert-manager-plugin-workflow_{context}"]
17+
== How the cert-manager plugin works
18+
19+
The cert-manager upstream authority plugin integrates SPIRE Server with cert-manager using the following workflow:
20+
21+
. SPIRE Server generates a certificate signing request (CSR) for an intermediate signing certificate.
22+
23+
. The plugin creates a `CertificateRequest` custom resource in the configured namespace.
24+
25+
. The `CertificateRequest` references the specified issuer by name, kind, and group.
26+
27+
. The cert-manager issuer processes the request and signs the certificate.
28+
29+
. SPIRE Server retrieves the signed certificate and CA bundle from the `CertificateRequest` resource.
30+
31+
. SPIRE Server uses the intermediate certificate to sign SPIFFE identities for workloads.
32+
33+
[id="cert-manager-plugin-requirements_{context}"]
34+
== Requirements and considerations
35+
36+
Before using the cert-manager upstream authority plugin, consider the following requirements:
37+
38+
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.
39+
40+
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.
41+
42+
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.
43+
44+
[id="cert-manager-plugin-configuration-options_{context}"]
45+
== Configuration options
46+
47+
The cert-manager upstream authority plugin supports the following configuration options:
48+
49+
Namespace:: Specifies the namespace where `CertificateRequest` resources are created. This is a required parameter.
50+
51+
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`).
52+
53+
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.
54+
55+
[id="cert-manager-plugin-deployment-modes_{context}"]
56+
== Deployment modes
57+
58+
You can deploy SPIRE Server with the cert-manager plugin in two configurations:
59+
60+
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.
61+
62+
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‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/spire/spire-upstream-authority-plugins.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-plugins-overview_{context}"]
7+
= Configuring SPIRE UpstreamAuthority plugins
8+
9+
[role="_abstract"]
10+
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.
11+
12+
You can configure SPIRE Server to use one of the following UpstreamAuthority plugins:
13+
14+
*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.
15+
16+
*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.
17+
18+
Choose the plugin that matches your certificate management infrastructure.

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

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/spire/cert-manager-upstream-authority-plugin.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-preparing-plugin-use_{context}"]
7+
= Preparing to use the cert-manager upstream authority plugin
8+
9+
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.
10+
11+
Prepare your cluster environment and configure required permissions so SPIRE Server can request certificates from cert-manager without manual intervention.
12+
13+
.Prerequisites
14+
15+
* A Kubernetes cluster running cert-manager.
16+
17+
* An issuer that supports providing signing certificates.
18+
19+
* Access to configure the SPIRE Server.
20+
21+
.Procedure
22+
23+
. Verify that cert-manager is running in your cluster by running the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc get pods -n cert-manager
28+
----
29+
+
30+
.Example output
31+
[source,terminal]
32+
----
33+
NAME READY STATUS RESTARTS AGE
34+
cert-manager-5d7f97b46d-8xxxx 1/1 Running 0 1d
35+
cert-manager-cainjector-69d885bf55-xxxxx 1/1 Running 0 1d
36+
cert-manager-webhook-54754dcdfd-xxxxx 1/1 Running 0 1d
37+
----
38+
39+
. Verify that you have an appropriate issuer configured that supports signing certificates by running the following command:
40+
+
41+
[source,terminal]
42+
----
43+
$ oc get issuer,clusterissuer -A
44+
----
45+
+
46+
.Example output
47+
[source,terminal]
48+
----
49+
NAMESPACE NAME READY AGE
50+
sandbox issuer.cert-manager.io/spire-ca True 1d
51+
----
52+
53+
. Identify or create a namespace where `CertificateRequests` are created by running the following command:
54+
+
55+
[source,terminal]
56+
----
57+
$ oc create namespace sandbox
58+
----
59+
60+
. Configure the required permissions:
61+
.. Create a service account for the SPIRE Server by running the following command:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc create serviceaccount spire-server -n sandbox
66+
----
67+
68+
.. Create a role with `create` permissions for `CertificateRequests` by running the following command:
69+
+
70+
[source,yaml]
71+
----
72+
apiVersion: rbac.authorization.k8s.io/v1
73+
kind: Role
74+
metadata:
75+
name: spire-server-cert-manager
76+
namespace: sandbox
77+
rules:
78+
- apiGroups: ["cert-manager.io"]
79+
resources: ["certificaterequests"]
80+
verbs: ["create", "get", "list", "watch"]
81+
----
82+
83+
.. Apply the role by running the following command:
84+
+
85+
[source,terminal]
86+
----
87+
$ oc apply -f spire-server-role.yaml
88+
----
89+
90+
.. Create a role binding to grant the service account the required permissions by running the following command:
91+
+
92+
[source,yaml]
93+
----
94+
apiVersion: rbac.authorization.k8s.io/v1
95+
kind: RoleBinding
96+
metadata:
97+
name: spire-server-cert-manager
98+
namespace: sandbox
99+
roleRef:
100+
apiGroup: rbac.authorization.k8s.io
101+
kind: Role
102+
name: spire-server-cert-manager
103+
subjects:
104+
- kind: ServiceAccount
105+
name: spire-server
106+
namespace: sandbox
107+
----
108+
109+
.. Apply the role binding by running the following command:
110+
+
111+
[source,terminal]
112+
----
113+
$ oc apply -f spire-server-rolebinding.yaml
114+
----
115+
116+
. Optional: If connecting from outside the cluster, extract the kubeconfig for the service account by running the following command:
117+
+
118+
[source,terminal]
119+
----
120+
$ oc create token spire-server -n sandbox --duration=8760h > /etc/kubernetes/kubeconfig
121+
----
122+
+
123+
Alternatively, create a complete kubeconfig file by running the following command:
124+
+
125+
[source,terminal]
126+
----
127+
$ oc config view --minify --flatten > /etc/kubernetes/kubeconfig
128+
----

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="zero-trust-manager-plugins"]
3+
= SPIRE UpstreamAuthority plugins for Zero Trust Workload Identity Manager
4+
include::_attributes/common-attributes.adoc[]
5+
:context: zero-trust-manager-plugins
6+
7+
toc::[]
8+
9+
[role="_abstract"]
10+
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.
11+
12+
// Configuring SPIRE UpstreamAuthority plugins
13+
include::modules/zero-trust-manager-plugins-overview.adoc[leveloffset=+1]
14+
15+
// About the cert-manager upstream authority plugin
16+
include::modules/zero-trust-manager-plugins-cert-manager-about.adoc[leveloffset=+1]
17+
18+
// Preparing to use the cert-manager upstream authority plugin
19+
include::modules/zero-trust-manager-preparing-plugin-use.adoc[leveloffset=+1]
20+
21+
// Preparing to use the cert-manager upstream authority plugin
22+
include::modules/zero-trust-manager-config-cert-manager.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)