Skip to content

Commit c394c1f

Browse files
author
Shubha Narayanan
committed
ZTWIM install uninstall overview
1 parent 3d7a5e1 commit c394c1f

18 files changed

+472
-0
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,3 +376,8 @@ endif::openshift-origin[]
376376
:hcp: hosted control planes
377377
:mce: multicluster engine for Kubernetes Operator
378378
:mce-short: multicluster engine Operator
379+
// Zero Trust Workload Identity Manager
380+
:zero-trust-full: Zero Trust Workload Identity Manager
381+
:spiffe-full: Secure Production Identity Framework for Everyone (SPIFFE)
382+
:svid-full: SPIFFE Verifiable Identity Document (SVID)
383+
:spire-full: SPIFFE Runtime Environment

‎_topic_maps/_topic_map.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1233,6 +1233,16 @@ Topics:
12331233
File: cert-manager-log-levels
12341234
- Name: Uninstalling the cert-manager Operator for Red Hat OpenShift
12351235
File: cert-manager-operator-uninstall
1236+
- Name: Zero Trust Workload Identity Manager
1237+
Dir: zero_trust_workload_identity_manager
1238+
Distros: openshift-enterprise
1239+
Topics:
1240+
- Name: Zero Trust Workload Identity Manager overview
1241+
File: zero-trust-manager-overview
1242+
- Name: Installing Zero Trust Workload Identity Manager
1243+
File: zero-trust-manager-install
1244+
- Name: Uninstalling Zero Trust Workload Identity Manager
1245+
File: zero-trust-manager-uninstall
12361246
- Name: Viewing audit logs
12371247
File: audit-log-view
12381248
- Name: Configuring the audit log policy

‎modules/zero-trust-manager-about-agent.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-about-agent_{context}"]
7+
= SPIRE agent
8+
9+
The SPIRE Agent is responsible for workload attestation, ensuring that workloads receive a verified identity when requesting authentication through the SPIFFE Workload API. It accomplishes this by using configured workload attestor plugins. In Kubernetes environments, the Kubernetes workload attestor plugin is used.
10+
11+
SPIRE and the SPIRE agent perform node attestation via node plugins. The plugins are used to verify the identity of the node on which the agent is running. For more information, see link:https://spiffe.io/docs/latest/spire-about/spire-concepts/#all-about-the-agent[About the SPIRE Agent].

‎modules/zero-trust-manager-about-attestation.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
2+
// Module included in the following assemblies:
3+
//
4+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-overview.adoc
5+
6+
:_mod-docs-content-type: CONCEPT
7+
[id="zero-trust-manager-about-attestation_{context}"]
8+
= Attestation
9+
10+
11+
Attestation is the process by which the identity of nodes and workloads are verified before SPIFFE IDs and SVIDs are issued. The SPIRE server gathers attributes of both the workload and node that the SPIRE Agent runs on, and then compares them to a set of selectors defined when the workload was registered. If the comparison is successful, the entities are provided with credentials. This ensures that only legitimate and expected entities within the trust domain receive cryptographic identities. The two main types of attestation in SPIFFE/SPIRE are:
12+
13+
* Node attestation: verifies the identity of a machine or a node on a system, before a SPIRE agent running on that node can be trusted to request identities for workloads.
14+
* Workload attestation: verifies the identity of an application or service running on an attested node before the SPIRE agent on that node can provide it with a SPIFFE ID and SVID.
15+
For more information, see link:https://spiffe.io/docs/latest/spire-about/spire-concepts/#attestation[Attestation].

‎modules/zero-trust-manager-about-spiffe.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-about-spiffe_{context}"]
7+
= SPIFFE
8+
9+
10+
{spiffe-full} provides a standardized way to establish trust between software workloads in distributed systems. SPIFFE assigns unique IDs called SPIFFE IDs. These IDs are Uniform Resource Identifiers (URI) that include a trust domain and a workload identifier.
11+
12+
The SPIFFE IDs are contained in the {svid-full}. SVIDs are used by workloads to verify their identity to other workloads so that the workloads can communicate with each other. The two main SVID formats are:
13+
14+
* X.509-SVIDs: X.509 certificates where the SPIFFE ID is embedded in the Subject Alternative Name (SAN) field.
15+
* JWT-SVIDs: JSON Web Tokens (JWTs) where the SPIFFE ID is included as the `sub` claim.
16+
For more information, see link:https://spiffe.io/docs/latest/spiffe-about/overview/[SPIFFE Overview].

‎modules/zero-trust-manager-about-spire.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
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-about-spire_{context}"]
7+
= SPIRE server
8+
9+
A SPIRE server is responsible for managing and issuing SPIFFE identities within a trust domain. It stores registration entries (selectors that determine under what conditions a SPIFFE ID should be issued) and signing keys. The SPIRE server works in conjunction with the SPIRE agent to perform node attestion via node plugins. For more information, see link:https://spiffe.io/docs/latest/spire-about/spire-concepts/#all-about-the-server[About the SPIRE server].

‎modules/zero-trust-manager-how-it-works.adoc

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
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-how-it-works_{context}"]
7+
= {zero-trust-full} workflow
8+
9+
10+
The following is a high-level workflow of the {zero-trust-full} within the Red{nbsp}Hat OpenShift cluster.
11+
12+
. The SPIRE, SPIRE agent, SPIFFE CSI Driver, and the SPIRE OIDC Discovery Provider operands are deployed and managed by {zero-trust-full} via associated Customer Resource Definitions (CRDs).
13+
14+
. Watches are then registered for relevant Kubernetes resources and the necessary SPIRE CRDs are applied to the cluster.
15+
16+
. The CR for the ZeroTrustWorkloadIdentityManager resource named `cluster` is deployed and managed by a controller.
17+
18+
. To deploy the SPIRE server, SPIRE agent, SPIFFE CSI Driver, and SPIRE OIDC Discovery Provider, you need to create a custom resource of a each certain type and name it `cluster`. The custom resource types are as follows:
19+
20+
* SPIRE server - `SpireServer`
21+
22+
* SPIRE agent - `SpireAgent`
23+
24+
* SPIFFE CSI Driver - `SpiffeCSIDriver`
25+
26+
* SPIRE OIDC discovery provider - `SpireOIDCDiscoveryProvider`
27+
28+
. When a node starts, the SPIRE agent initializes, and connects to the SPIRE server.
29+
30+
. The agent begins the node attestation process. The agent collects information on the node's identity such as label name and namespace. The agent securely provides the information it gathered through the attestation to the SPIRE server.
31+
32+
. The SPIRE server then evaluates this information against its configured attestation policies and registration entries. If successful, the server generates an agent SVID and the Trust Bundle (CA Certificate) and securely sends this back to the agent.
33+
34+
. A workload starts on the node and needs a secure identity. The workload connects to the agent's Workload API and requests a SVID.
35+
36+
. The agent receives the request and begins a workload attestation to gather information about the workload.
37+
38+
. After the agent gathers the information, the information is sent to the SPIRE server and the server checks its configured registration entries.
39+
40+
. The agent receives the workload SVID and Trust Bundle and passes it on to the workload. The workload can now present their SVIDs to other SPIFFE-aware devices to communicate with them.
41+
42+
[role="_additional-resources"]
43+
.Additional resources
44+
45+
* link:https://spiffe.io/docs/latest/deploying/registering/[Registering workloads]
46+
47+
* link:https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/[SPIFFE Concepts]
48+
49+
* link:https://spiffe.io/docs/latest/spire-about/use-cases/[SPIRE Use Cases]

‎modules/zero-trust-manager-install-cli.adoc

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/ Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manageer/zero-trust-manager-install.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-install-cli_{context}"]
7+
= Installing the {zero-trust-full} by using the CLI
8+
9+
.Prerequisites
10+
11+
* You have access to the cluster with `cluster-admin` privileges.
12+
.Procedure
13+
14+
. Create a new project named `zero-trust-workload-identity-manager` by running the following command:
15+
+
16+
[source, terminal]
17+
----
18+
$ oc new-project zero-trust-workload-identity-manager
19+
----
20+
21+
. Create an `OperatorGroup` object:
22+
23+
.. Create a YAML file, for example, `operatorGroup.yaml`, with the following content:
24+
+
25+
.Example `operatorGroup.yaml`
26+
+
27+
[source, yaml]
28+
----
29+
apiVersion: operators.coreos.com/v1
30+
kind: OperatorGroup
31+
metadata:
32+
name: openshift-zero-trust-workload-identity-manager
33+
namespace: zero-trust-workload-identity-manager
34+
spec:
35+
upgradeStrategy: Default
36+
----
37+
38+
.. Create the `OperatorGroup` object by running the following command:
39+
+
40+
[source, terminal]
41+
----
42+
$ oc create -f operatorGroup.yaml
43+
----
44+
45+
. Create a `Subscription` object:
46+
47+
.. Create a YAML file, for example, `subscription.yaml`, that defines the `Subscription` object:
48+
+
49+
.Example `subscription.yaml`
50+
+
51+
[source, yaml]
52+
----
53+
apiVersion: operators.coreos.com/v1alpha1
54+
kind: Subscription
55+
metadata:
56+
name: openshift-zero-trust-workload-identity-manager
57+
namespace: zero-trust-workload-identity-manager
58+
spec:
59+
channel: tech-preview-v0.1
60+
name: openshift-zero-trust-workload-identity-manager
61+
source: redhat-operators
62+
sourceNamespace: openshift-marketplace
63+
installPlanApproval: Automatic
64+
----
65+
66+
.. Create the `Subscription` object by running the following command:
67+
+
68+
[source, terminal]
69+
----
70+
$ oc create -f subscription.yaml
71+
----
72+
73+
.Verification
74+
75+
. Verify that the OLM subscription is created by running the following command:
76+
+
77+
[source, terminal]
78+
----
79+
$ oc get subscription -n zero-trust-workload-identity-manager
80+
----
81+
+
82+
.Example output
83+
[source, terminal]
84+
----
85+
NAME PACKAGE SOURCE CHANNEL
86+
openshift-zero-trust-workload-identity-manager zero-trust-workload-identity-manager redhat-operators tech-preview-v0.1
87+
----
88+
89+
. Verify whether the Operator is successfully installed by running the following command:
90+
+
91+
[source, terminal]
92+
----
93+
$ oc get csv -n zero-trust-workload-identity-manager
94+
----
95+
+
96+
.Example output
97+
[source, terminal]
98+
----
99+
NAME DISPLAY VERSION PHASE
100+
zero-trust-workload-identity-manager.v0.1.0 Zero Trust Workload Identity Manager 0.1.0 Succeeded
101+
----
102+
103+
. Verify that the {zero-trust-full} controller manager is ready by running the following command:
104+
+
105+
[source, terminal]
106+
----
107+
$ oc get deployment -l name=zero-trust-workload-identity-manager -n zero-trust-workload-identity-manager
108+
----
109+
+
110+
.Example output
111+
[source, terminal]
112+
----
113+
NAME READY UP-TO-DATE AVAILABLE AGE
114+
zero-trust-workload-identity-manager-controller-manager 1/1 1 1 43m
115+
----

‎modules/zero-trust-manager-install-console.adoc

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zer-trust-manager-install.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-install-console_{context}"]
7+
= Installing the {zero-trust-full} by using the web console
8+
9+
You can use the web console to install the {zero-trust-full}.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster with `cluster-admin` privileges.
14+
* You have access to the {product-title} web console.
15+
.Procedure
16+
17+
. Log in to the {product-title} web console.
18+
19+
. Go to *Operators* -> *OperatorHub*.
20+
21+
. Enter *{zero-trust-full}* into the filter box.
22+
23+
. Select the *{zero-trust-full}*
24+
25+
. Select the {zero-trust-full} version from *Version* drop-down list, and click *Install*.
26+
27+
. On the *Install Operator* page:
28+
.. Update the *Update channel*, if necessary. The channel defaults to *tech-preview-v0.1*, which installs the latest Technology Preview v0.1 release of the {zero-trust-full}.
29+
.. Choose the *Installed Namespace* for the Operator. The default Operator namespace is `zero-trust-workload-identity-manager`.
30+
+
31+
If the `zero-trust-workload-identity-manager` namespace does not exist, it is created for you.
32+
33+
.. Select an *Update approval* strategy.
34+
+
35+
* The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available.
36+
+
37+
* The *Manual* strategy requires a user with appropriate credentials to approve the Operator update.
38+
.. Click *Install*.
39+
40+
.Verification
41+
42+
. Navigate to *Operators* -> *Installed Operators*.
43+
44+
. Verify that *{zero-trust-full}* is listed with a *Status* of *Succeeded* in the `zero-trust-workload-identity-manager` namespace.
45+
46+
. Verify that {zero-trust-full} controller manager deployment is ready and available by running the following command:
47+
+
48+
[source,terminal]
49+
----
50+
$ oc get deployment -l name=zero-trust-workload-identity-manager -n zero-trust-workload-identity-manager
51+
----
52+
+
53+
.Example output
54+
[source,terminal]
55+
----
56+
NAME READY UP-TO-DATE AVAILABLE AGE
57+
zero-trust-workload-identity-manager-controller-manager-6c4djb 1/1 1 1 43m
58+
----

‎modules/zero-trust-manager-uninstall-console.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-uninstall.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-uninstall-console_{context}"]
7+
= Uninstalling the {zero-trust-full}
8+
9+
You can uninstall the {zero-trust-full} by using the web console.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster with `cluster-admin` privileges.
14+
15+
* You have access to the {product-title} web console.
16+
17+
* The {zero-trust-full} is installed.
18+
.Procedure
19+
20+
. Log in to the {product-title} web console.
21+
22+
. Uninstall the {zero-trust-full}.
23+
24+
.. Go to *Operators* -> *Installed Operators*.
25+
26+
.. Click the *Options* menu next to the *{zero-trust-full}* entry, and then click *Uninstall Operator*.
27+
28+
.. In the confirmation dialog, click *Uninstall*.

0 commit comments

Comments
 (0)