Skip to content

Commit 9c33bb4

Browse files
wgabor0427wgabor0427
committed
OSDOCS-15489 updated vault module
1 parent 33c720e commit 9c33bb4

8 files changed

+249
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1239,6 +1239,8 @@ Topics:
12391239
File: zero-trust-manager-install
12401240
- Name: Deploying Zero Trust Workload Identity Manager operands
12411241
File: zero-trust-manager-configuration
1242+
- Name: Zero Trust Workload Identity Manager upstream authority plugins
1243+
File: zero-trust-manager-upstream-authority
12421244
- Name: Monitoring Zero Trust Workload Identity Manager
12431245
File: zero-trust-manager-monitoring
12441246
- Name: Uninstalling Zero Trust Workload Identity Manager

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-cert-manager-crd_{context}"]
7+
= Configuring cert-manager plugin using the SPIRE server CRD
8+
9+
To configure the cert-manager plugin using the SPIRE server Custom Resource Defnition (CRD), perform the following steps:
10+
11+
.Procedure
12+
13+
. 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.
14+
+
15+
.Example `spireserver.yaml`
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: operator.openshift.io/v1alpha1
20+
kind: SpireServer
21+
metadata:
22+
name: cluster
23+
spec:
24+
trustDomain: "example.org"
25+
upstreamAuthority:
26+
type: "cert-manager"
27+
upstreamAuthorityCertManager:
28+
issuerName: "ca-issuer" <1>
29+
issuerKind: "ClusterIssuer" <2>
30+
issuerGroup: "cert-manager.io" <3>
31+
namespace: "zero-trust-workload-identity-manager" <4>
32+
kubeConfigSecretName: "external-cluster-kubeconfig" <5>
33+
----
34+
<1> The name of the `cert-manager` Issuer or ClusterIssuer that signs the `certificateRequest`.
35+
<2> Set to `ClusterIssuer` if issuer is cluster-scoped. The default is `Issuer`.
36+
<3> The API group of the issuer. The default is `cert-manager.io`.
37+
<4> The namespace where the `CertificateRequest` is created. The default is `zero-trust-workload-identity-manager`.
38+
<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.
39+
40+
. Apply the configuration by running the following command:
41+
+
42+
[source, terminal]
43+
----
44+
$ oc apply -f spireserver.yaml
45+
----
46+
47+
.Verification
48+
49+
. Run the following command to list the `CertificateRequest` resources in the namespace where the SPIRE server creates them.
50+
+
51+
[source, terminal]
52+
----
53+
$ oc get certificaterequests -n <namespace>
54+
----
55+
56+
. 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.
57+
+
58+
[source, terminal]
59+
----
60+
$ oc describe certificaterequest <name-of-cert-request> -n <namespace>
61+
----

‎modules/zero-trust-manager-cert-manager-upstream-authority.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-cert-manager-upstream-authority_{context}"]
7+
= About the cert-manager upstream authority plugin
8+
9+
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.
10+
11+
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.

‎modules/zero-trust-manager-configure-cert-manager.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/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-configure-cert-manager_{context}"]
7+
= Configuring the cert-manager plugin
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* Access to a Kubernetes cluster where the SPIRE server runs.
14+
15+
* 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].
16+
17+
* A pre-configured cert-manager `Issuer` capable of signing intermediate Certificate Authority (CA) certificates.
18+

‎modules/zero-trust-manager-configure-issuer.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority plugins.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-configure-issuer_{context}"]
7+
= Configuring the cert-manager issuer
8+
9+
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:
10+
11+
.Procedure
12+
13+
. Generate the Transport Layer Security (TLS) secret by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc create secret tls my-ca-key-pair-secret \
18+
--cert=path/to/your/ca.crt \
19+
--key=path/to/your/ca.key \
20+
--namespace=my-namespace
21+
----
22+
23+
. Create a YAML file that defines the `Issuer`, for example `ca-issuer.yaml`:
24+
+
25+
.Example `ca-issuer.yaml`
26+
+
27+
[source,yaml]
28+
----
29+
apiVersion: cert-manager.io/v1
30+
kind: Issuer
31+
metadata:
32+
name: my-ca-issuer
33+
namespace: my-namespace
34+
spec:
35+
ca:
36+
secretName: my-ca-key-pair-secret <1>
37+
----
38+
<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`.
39+
40+
. Apply the configuration by running the following command:
41+
+
42+
[source, terminal]
43+
----
44+
$ oc apply -f ca-issuer.yaml
45+
----

‎modules/zero-trust-manager-configure-vault.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zer_trust_workload_identity_manager/zero-trust-manager.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-configure-cert-vault_{context}"]
7+
= Configuring the Vault plugin
8+
9+
This procedure outlines the steps required to configure a SPIRE server to obtain its intermediate signing certificates from Vault. The plugin supports the following methodes for authenticating to Vault:
10+
11+
* Client Certificate Authentication
12+
13+
* Token Authentication
14+
15+
* AppRole Authentication
16+
17+
* Kubernetes Authentication
18+
19+
.Prerequisites
20+
21+
* A running and accessible HashiCorp Vault server is available.
22+
23+
* A PKI secret engine must be enabled and configured in Vault at the specified `pki_mount_point`.
24+
25+
* A role within the Vault PKI engine must be configured to allow issuing of intermediate CA certificates.
26+
27+
* The Vault token or authentication method used by the plugin must have the necessary permissions.
28+
29+
* The `ca_ttl` configured in your SPIRE Server configuration must be less than or equal to the cofigured `max_lease_ttl` of the Vault PKI secret engine role that the plugin uses.
30+
31+
32+
33+
.Procedure
34+
35+
. 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 `vault` plugin.
36+
+
37+
.Example `spireserver.yaml`
38+
+
39+
[source,yaml]
40+
----
41+
apiVersion: spire.spiffe.io/v1alpha1
42+
kind: SpireServer
43+
metadata:
44+
name: spire-server
45+
namespace: spire
46+
spec:
47+
replicas: 1
48+
# ... other SpireServer configuration ...
49+
upstreamAuthority:
50+
vault:
51+
address: "https://vault.example.com" <1>
52+
tokenPath: "/var/run/secrets/kubernetes.io/serviceaccount/token" <2>
53+
mtls:
54+
spireTrustDomain: "spiffe://example.org" <3>
55+
serverName: "vault.example.com" <4>
56+
pkcs11: <5>
57+
# ... PKCS11 configuration if needed ...
58+
jwt: <5>
59+
# ... JWT configuration if needed ...
60+
----
61+
62+
<1> The URL of your Vault server.
63+
<2> The path to the Kubernetes service account token used for authentication with Vault.
64+
<3> The trust domain of your Spire Server.
65+
<4> The name used for the Mutual Transport Layer Security (mTLS) authentication with the Vault server.
66+
<5> Alternative authentication methods with Vault.
67+
68+
. Configure one of the authentication methods:
69+
70+
71+
72+
. Apply the configuration by running the following command:
73+
+
74+
[source, terminal]
75+
----
76+
$ oc apply -f spireserver.yaml
77+
----

‎modules/zero-trust-manager-vault-upstream-authority.adoc‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="zero-trust-manager-vault-upstream-authority_{context}"]
7+
= About the vault upstream authority plugin
8+
9+
The vault plugin integrates the SPIRE server with the HashiCorp Vault Public Key Infrastructure (PKI) engine to manage the lifecycle of intermediate CA certificates that the SPIRE server uses to sign the workload {svid-full}. The plugin enables the SPIRE server to use the PKI for issuing and renewing intermediate signing certificates.
10+
11+
The plugin interacts with the PKI secret engine to request intermediate CA certificates, signs the requests, and then provides the certificates to the SPIRE server.
12+
13+
[NOTE]
14+
====
15+
The vault plugin does not support the `PublishJWTKey` remote procedure call (RPC) and should not be used in SPIRE configurations where JSON Web Tokens-SPIFFE Verifiable Identity Documents (JWT-SVIDs) are used.
16+
====

‎security/zero_trust_workload_identity_manager/zero-trust-manager-upstream-authority.adoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="zero-trust-manager-upstream-authority-plugins"]
3+
= Zero Trust Workload Identity Manager upstream authority plugins
4+
5+
include::_attributes/common-attributes.adoc[]
6+
:context: zero-trust-manager-overview
7+
8+
toc::[]
9+
10+
:FeatureName: Zero Trust Workload Identity Manager
11+
include::snippets/technology-preview.adoc[]
12+
13+
Upstream authority plugins are components that allow the SPIRE server to integrate with an existing Public Key Infrastructure (PKI) to obtain intermediate signing certificates. The SPIRE server then uses these intermediate certificates to cryptographically sign the {svid-full} that it issues to workloads. The plugins also allow the SPIRE server to use a pre-existing root of trust, rather than establishing a new, isolated one.
14+
15+
The following upstream authority plugins are available:
16+
17+
* cert-manager
18+
19+
* vault

0 commit comments

Comments
 (0)