Skip to content

Commit 43ec5f2

Browse files
stevsmitstevsmit
authored
Merge pull request #103787 from wgabor0427/OSDOCS-17246
OSDOCS-17246 created doc for spire federation
2 parents f4bf40c + 7d67fda commit 43ec5f2

11 files changed

+1540
-22
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1244,6 +1244,8 @@ Topics:
12441244
File: zero-trust-manager-configuration
12451245
- Name: Configuring Zero Trust Workload Identity Manager OIDC Federation
12461246
File: zero-trust-manager-oidc-federation
1247+
- Name: Configuring Zero Trust Workload Identity Manager SPIRE Federation
1248+
File: zero-trust-manager-spire-federation
12471249
- Name: Enabling create-only mode for the Zero Trust Workload Identity Manager
12481250
File: zero-trust-manager-reconciliation
12491251
- Name: Monitoring Zero Trust Workload Identity Manager

‎modules/zero-trust-manager-automatic-management.adoc‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/zero_trust_workload_identity_manager/zero-trust-manager-spire-federation.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="zero-trust-manager-automatic-management_{context}"]
7+
= Using SPIRE federation with Automatic Certificate Management Environment protocol
8+
9+
[role="_abstract"]
10+
Using SPIRE federation with Automatic Certificate Management Environment (ACME) protocol provides automatic certificate provisioning from Let's Encrypt. ACME also enables automatic certificate renewal before expiration, eliminating manual certificate management overhead.
11+
12+
.Prerequisites
13+
14+
* You have installed the {zero-trust-full} on all clusters that will participate in the federation.
15+
16+
* You have installed the OpenShift CLI (`oc`).
17+
18+
* You have `cluster-admin` privileges on all participating clusters.
19+
20+
* Your federation endpoints must be publicly accessible for Let's Encrypt HTTP-01 challenge validation.
21+
22+
* You have network connectivity between all federated clusters.
23+
24+
25+
.Procedure
26+
27+
. Configure the `SpireServer` custom resource on each cluster to enable federation with ACME certificate management.
28+
+
29+
Create or update your `SpireServer` resource with the federation configuration:
30+
+
31+
[source,yaml]
32+
----
33+
apiVersion: operator.openshift.io/v1alpha1
34+
kind: SpireServer
35+
metadata:
36+
name: cluster
37+
spec:
38+
trustDomain: cluster1.example.com
39+
federation:
40+
bundleEndpoint:
41+
profile: https_web
42+
refreshHint: 300
43+
httpsWeb:
44+
acme:
45+
directoryUrl: https://acme-v02.api.letsencrypt.org/directory
46+
domainName: federation.apps.cluster1.example.com
47+
email: admin@example.com
48+
tosAccepted: "true"
49+
managedRoute: "true"
50+
----
51+
52+
* The `trustDomain` field sets a unique trust domain for each cluster (for example, `cluster1.example.com`, `cluster2.example.com`).
53+
54+
* The `profile` field uses the `https_web` profile for ACME-based certificate management.
55+
56+
* The `directoryUrl` field contains the Let's Encrypt production directory URL. For testing, use: `https://acme-staging-v02.api.letsencrypt.org/directory`.
57+
58+
* The `domainName` field is the domain name where your federation endpoint is accessible. This automatically sets to `federation.<cluster-apps-domain>` if `managedRoute` is set to "true".
59+
60+
* The `email` field is your email address for ACME account registration and certificate expiration notifications.
61+
62+
* The `tosAccepted` field accepts the Let's Encrypt Terms of Service.
63+
64+
* The `managedRoute` field enables an automatic route creation by the operator for the federation bundle endpoint.
65+
66+
. Apply the configuration to each cluster by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc apply -f spireserver.yaml
71+
----
72+
73+
. Check the status of the SPIRE Server by entering the following command. Wait for the `Ready` status to be returned before proceeding to the next step.
74+
+
75+
[source,terminal]
76+
----
77+
$ oc get spireserver cluster -w
78+
----
79+
+
80+
.Example output
81+
[source,terminal]
82+
----
83+
NAME STATUS AGE
84+
cluster Ready 5m
85+
----
86+
87+
. Verify that the federation route has been created by running the following command:
88+
+
89+
[source,terminal]
90+
----
91+
$ oc get route -n zero-trust-workload-identity-manager | grep federation
92+
----
93+
+
94+
.Example output
95+
[source,terminal]
96+
----
97+
NAME HOST/PORT PATH SERVICES PORT TERMINATION
98+
spire-server-federation federation.apps.cluster1.example.com spire-server 8443 passthrough
99+
----
100+
101+
. On each cluster, fetch the trust bundle from the federation endpoint by running the following command:
102+
+
103+
[source,terminal]
104+
----
105+
$ curl https://federation.apps.cluster1.example.com > cluster1-bundle.json
106+
----
107+
+
108+
The response contains the trust bundle in JSON Web Key Set (JWKS) format:
109+
+
110+
.Example trust bundle
111+
[source,json]
112+
----
113+
{
114+
"keys": [
115+
{
116+
"use": "x509-svid",
117+
"kty": "RSA",
118+
"n": "...",
119+
"e": "AQAB",
120+
"x5c": ["..."]
121+
}
122+
],
123+
"spiffe_sequence": 1,
124+
"refresh_hint": 300
125+
}
126+
----
127+
128+
. Create `ClusterFederatedTrustDomain` resources to establish federation relationships.
129+
+
130+
.. On Cluster 1, create resources to federate with Cluster 2 and Cluster 3:
131+
+
132+
[source,yaml]
133+
----
134+
apiVersion: spire.spiffe.io/v1alpha1
135+
kind: ClusterFederatedTrustDomain
136+
metadata:
137+
name: cluster2-federation
138+
spec:
139+
trustDomain: cluster2.example.com
140+
bundleEndpointURL: https://federation.apps.cluster2.example.com
141+
bundleEndpointProfile:
142+
type: https_web
143+
trustDomainBundle: |
144+
{
145+
"keys": [...],
146+
"spiffe_sequence": 1
147+
}
148+
---
149+
apiVersion: spire.spiffe.io/v1alpha1
150+
kind: ClusterFederatedTrustDomain
151+
metadata:
152+
name: cluster3-federation
153+
spec:
154+
trustDomain: cluster3.example.com
155+
bundleEndpointURL: https://federation.apps.cluster3.example.com
156+
bundleEndpointProfile:
157+
type: https_web
158+
trustDomainBundle: |
159+
{
160+
"keys": [...],
161+
"spiffe_sequence": 1
162+
}
163+
----
164+
165+
* The `trustDomainBundle` field contains the complete trust bundle JSON that you fetched using `curl` in step 5.
166+
167+
. Apply the `ClusterFederatedTrustDomain` resources by running the following command:
168+
+
169+
[source,terminal]
170+
----
171+
$ oc apply -f cluster-federated-trust-domains.yaml
172+
----
173+
174+
. Repeat steps 6 and 7 on each cluster to establish bidirectional federation. Each cluster needs `ClusterFederatedTrustDomain` resources for every other cluster it federates with.
175+
176+
. Update the `SpireServer` resource on each cluster to add the `federatesWith` configuration:
177+
+
178+
[source,yaml]
179+
----
180+
apiVersion: operator.openshift.io/v1alpha1
181+
kind: SpireServer
182+
metadata:
183+
name: cluster
184+
spec:
185+
# ... existing configuration ...
186+
federation:
187+
bundleEndpoint:
188+
# ... existing bundleEndpoint configuration ...
189+
federatesWith:
190+
- trustDomain: cluster2.example.com
191+
bundleEndpointUrl: https://federation.apps.cluster2.example.com
192+
bundleEndpointProfile: https_web
193+
- trustDomain: cluster3.example.com
194+
bundleEndpointUrl: https://federation.apps.cluster3.example.com
195+
bundleEndpointProfile: https_web
196+
managedRoute: "true"
197+
----
198+
199+
* The `federatesWith` field lists all remote trust domains this cluster should federate with.
200+
201+
. Apply the updated configuration by running the following command:
202+
+
203+
[source,terminal]
204+
----
205+
$ oc apply -f spireserver.yaml
206+
----
207+
208+
.Verification
209+
210+
. Verify that the `ClusterFederatedTrustDomain` resources have been created by running the following command:
211+
+
212+
[source,terminal]
213+
----
214+
$ oc get clusterfederatedtrustdomains
215+
----
216+
+
217+
.Example output
218+
[source,terminal]
219+
----
220+
NAME TRUST DOMAIN ENDPOINT URL AGE
221+
cluster2-federation cluster2.example.com https://federation.apps.cluster2.example.com 5m
222+
cluster3-federation cluster3.example.com https://federation.apps.cluster3.example.com 5m
223+
----
224+
225+
. Check the status of a `ClusterFederatedTrustDomain` to ensure bundle synchronization is working by running the following command:
226+
+
227+
[source,terminal]
228+
----
229+
$ oc describe clusterfederatedtrustdomain cluster2-federation
230+
----
231+
+
232+
Look for `Successful` status conditions indicating that the trust bundle has been synchronized.
233+
234+
. Verify that the federation endpoint is accessible and serving the trust bundle by running the following command:
235+
+
236+
[source,terminal]
237+
----
238+
$ curl https://federation.apps.cluster1.example.com
239+
----
240+
+
241+
You should receive a JSON response containing the trust bundle.
242+
243+
. Check the SPIRE Server logs to confirm federation is active by running the following command:
244+
+
245+
[source,terminal]
246+
----
247+
$ oc logs -n zero-trust-workload-identity-manager deployment/spire-server -c spire-server --tail=50
248+
----
249+
+
250+
Look for log messages indicating successful bundle synchronization with federated trust domains.
251+
252+
. Verify that all SPIRE components are running by running the following command:
253+
+
254+
[source,terminal]
255+
----
256+
$ oc get pods -n zero-trust-workload-identity-manager
257+
----
258+
+
259+
.Example output
260+
[source,terminal]
261+
----
262+
NAME READY STATUS RESTARTS AGE
263+
spire-agent-abcde 1/1 Running 0 10m
264+
spire-server-0 2/2 Running 0 10m
265+
----
266+
267+
. Optional: Test cross-cluster workload authentication by deploying workloads with SPIFFE identities on different clusters and verifying they can authenticate to each other using the federated trust.
268+
269+

0 commit comments

Comments
 (0)