Skip to content

Commit 2dfa746

Browse files
negznegz
authored
Merge pull request #711 from negz/server-side
Document the --enable-claim-ssa feature flag
2 parents 83a3d08 + cc7020d commit 2dfa746

File tree

5 files changed

+213
-0
lines changed

5 files changed

+213
-0
lines changed

‎content/master/concepts/server-side-apply.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Server-Side Apply
3+
state: alpha
4+
alphaVersion: "1.15"
5+
weight: 300
6+
---
7+
8+
Crossplane can use server-side apply to sync claims with composite resources
9+
(XRs), and to sync composite resources with composed resources.
10+
11+
When Crossplane uses server-side apply, the Kubernetes API server helps sync
12+
resources. Using server-side apply makes syncing more predictable and less
13+
buggy.
14+
15+
{{<hint "tip">}}
16+
Server-side apply is a Kubernetes feature. Read more about server-side apply in
17+
the [Kubernetes documentation](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
18+
{{</hint>}}
19+
20+
## Use server-side apply to sync claims with composite resources
21+
22+
When you create a claim, Crossplane creates a corresponding composite resource.
23+
Crossplane keeps the claim in sync with the composite resource. When you change
24+
the claim, Crossplane reflects those changes on the composite resource.
25+
26+
Read the [claims documentation]({{<ref "./claims">}}) to learn more about claims
27+
and how they relate to composite resources.
28+
29+
Crossplane can use server-side apply to keep the claim in sync with the
30+
composite resource.
31+
32+
Use the `--enable-ssa-claims` feature flag to enable using server-side apply.
33+
Read the [Install Crossplane documentation]({{<ref "../software/install#feature-flags">}})
34+
to learn about feature flags.
35+
36+
If you see fields reappearing after you delete them from a claim's `spec`,
37+
enable server-side apply to fix the problem. Enabling server-side apply also
38+
fixes the problem where Crossplane doesn't delete labels and annotations from
39+
the composite resource when you delete them from the claim.
40+
41+
{{<hint "important">}}
42+
When you enable server-side apply, Crossplane is stricter about how it syncs
43+
a claim with its counterpart composite resource:
44+
45+
- The claim's `metadata` syncs to the composite resource's `metadata`.
46+
- The claim's `spec` syncs to the composite resource's `spec`.
47+
- The composite resource's `status` syncs to the claim's `status`.
48+
49+
When you enable server-side apply Crossplane doesn't sync the composite resource's `metadata`
50+
and `spec` back to the claim's `metadata` and `spec`. It also doesn't sync the
51+
claim's `status` to the composite resource's `status`.
52+
{{</hint>}}
53+
54+
## Use server-side apply to sync claims end-to-end
55+
56+
To get the full benefit of server-side apply, use the `--enable-ssa-claims`
57+
feature flag together with composition functions.
58+
59+
When you use composition functions, Crossplane uses server side apply to sync
60+
composite resources with composed resources. Read more about this in the
61+
[composition functions documentation]({{<ref "./composition-functions#how-composition-functions-work">}}).
62+
63+
```mermaid
64+
graph LR
65+
A(Claim) -- claim server-side apply --> B(Composite Resource)
66+
B -- function server-side apply --> C(Composed Resource)
67+
B -- function server-side apply --> D(Composed Resource)
68+
B -- function server-side apply --> E(Composed Resource)
69+
```
70+
71+
When you use server-side apply end-to-end there is a clear, predictable
72+
propagation of fields from claim to composed resources, and back:
73+
74+
* `metadata` and `spec` flow forwards, from claim to XR to composed resources.
75+
* `status` flows backwards, from composed resources to XR to claim.
76+
77+
{{<hint "important">}}
78+
When you use composition functions, Crossplane is stricter about how it syncs
79+
composite resources (XRs) with composed resources:
80+
81+
- The XR's `metadata` syncs to the composed resource's `metadata`.
82+
- The XR's `spec` syncs to the composed resource's `spec`.
83+
- The composed resource's `status` syncs to the XR's `status`.
84+
85+
When you use composition functions Crossplane doesn't sync the composed resource's `metadata`
86+
and `spec` back to the XR's `metadata` and `spec`.
87+
{{</hint>}}
88+
89+
When Crossplane uses server-side apply end-to-end to sync claims with composed
90+
resources, it deletes fields from a composed resource's `spec` when you
91+
delete fields from the claim's `spec`.
92+
93+
When Crossplane uses server-side apply end-to-end it's also able to merge claim
94+
fields into complex composed resource fields. Objects and arrays of objects are
95+
examples of complex composed resource fields.
96+
97+
{{<hint "tip">}}
98+
Crossplane can only merge complex fields for resources that use server-side
99+
apply merge strategy OpenAPI extensions. Read about these extensions in the
100+
Kubernetes [server-side apply documentation](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy).
101+
102+
If you find that Crossplane isn't merging managed resource fields, raise an
103+
issue against the relevant provider. Ask the provider maintainer to add
104+
server-side apply merge strategy extensions to the managed resource.
105+
{{</hint>}}

‎content/master/software/install.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,7 @@ at the table below.
254254
| Alpha | `--enable-external-secret-stores` | Enable support for External Secret Stores. |
255255
| Alpha | `--enable-usages` | Enable support for Usages. |
256256
| Alpha | `--enable-realtime-compositions` | Enable support for real time compositions. |
257+
| Alpha | `--enable-ssa-claims` | Enable support for using server-side apply to sync claims with XRs. |
257258
{{< /table >}}
258259
{{< /expand >}}
259260

‎content/v1.15/concepts/server-side-apply.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: Server-Side Apply
3+
state: alpha
4+
alphaVersion: "1.15"
5+
weight: 300
6+
---
7+
8+
Crossplane can use server-side apply to sync claims with composite resources
9+
(XRs), and to sync composite resources with composed resources.
10+
11+
When Crossplane uses server-side apply, the Kubernetes API server helps sync
12+
resources. Using server-side apply makes syncing more predictable and less
13+
buggy.
14+
15+
{{<hint "tip">}}
16+
Server-side apply is a Kubernetes feature. Read more about server-side apply in
17+
the [Kubernetes documentation](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
18+
{{</hint>}}
19+
20+
## Use server-side apply to sync claims with composite resources
21+
22+
When you create a claim, Crossplane creates a corresponding composite resource.
23+
Crossplane keeps the claim in sync with the composite resource. When you change
24+
the claim, Crossplane reflects those changes on the composite resource.
25+
26+
Read the [claims documentation]({{<ref "./claims">}}) to learn more about claims
27+
and how they relate to composite resources.
28+
29+
Crossplane can use server-side apply to keep the claim in sync with the
30+
composite resource.
31+
32+
Use the `--enable-ssa-claims` feature flag to enable using server-side apply.
33+
Read the [Install Crossplane documentation]({{<ref "../software/install#feature-flags">}})
34+
to learn about feature flags.
35+
36+
If you see fields reappearing after you delete them from a claim's `spec`,
37+
enable server-side apply to fix the problem. Enabling server-side apply also
38+
fixes the problem where Crossplane doesn't delete labels and annotations from
39+
the composite resource when you delete them from the claim.
40+
41+
{{<hint "important">}}
42+
When you enable server-side apply, Crossplane is stricter about how it syncs
43+
a claim with its counterpart composite resource:
44+
45+
- The claim's `metadata` syncs to the composite resource's `metadata`.
46+
- The claim's `spec` syncs to the composite resource's `spec`.
47+
- The composite resource's `status` syncs to the claim's `status`.
48+
49+
When you enable server-side apply Crossplane doesn't sync the composite resource's `metadata`
50+
and `spec` back to the claim's `metadata` and `spec`. It also doesn't sync the
51+
claim's `status` to the composite resource's `status`.
52+
{{</hint>}}
53+
54+
## Use server-side apply to sync claims end-to-end
55+
56+
To get the full benefit of server-side apply, use the `--enable-ssa-claims`
57+
feature flag together with composition functions.
58+
59+
When you use composition functions, Crossplane uses server side apply to sync
60+
composite resources with composed resources. Read more about this in the
61+
[composition functions documentation]({{<ref "./composition-functions#how-composition-functions-work">}}).
62+
63+
```mermaid
64+
graph LR
65+
A(Claim) -- claim server-side apply --> B(Composite Resource)
66+
B -- function server-side apply --> C(Composed Resource)
67+
B -- function server-side apply --> D(Composed Resource)
68+
B -- function server-side apply --> E(Composed Resource)
69+
```
70+
71+
When you use server-side apply end-to-end there is a clear, predictable
72+
propagation of fields from claim to composed resources, and back:
73+
74+
* `metadata` and `spec` flow forwards, from claim to XR to composed resources.
75+
* `status` flows backwards, from composed resources to XR to claim.
76+
77+
{{<hint "important">}}
78+
When you use composition functions, Crossplane is stricter about how it syncs
79+
composite resources (XRs) with composed resources:
80+
81+
- The XR's `metadata` syncs to the composed resource's `metadata`.
82+
- The XR's `spec` syncs to the composed resource's `spec`.
83+
- The composed resource's `status` syncs to the XR's `status`.
84+
85+
When you use composition functions Crossplane doesn't sync the composed resource's `metadata`
86+
and `spec` back to the XR's `metadata` and `spec`.
87+
{{</hint>}}
88+
89+
When Crossplane uses server-side apply end-to-end to sync claims with composed
90+
resources, it deletes fields from a composed resource's `spec` when you
91+
delete fields from the claim's `spec`.
92+
93+
When Crossplane uses server-side apply end-to-end it's also able to merge claim
94+
fields into complex composed resource fields. Objects and arrays of objects are
95+
examples of complex composed resource fields.
96+
97+
{{<hint "tip">}}
98+
Crossplane can only merge complex fields for resources that use server-side
99+
apply merge strategy OpenAPI extensions. Read about these extensions in the
100+
Kubernetes [server-side apply documentation](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy).
101+
102+
If you find that Crossplane isn't merging managed resource fields, raise an
103+
issue against the relevant provider. Ask the provider maintainer to add
104+
server-side apply merge strategy extensions to the managed resource.
105+
{{</hint>}}

‎utils/vale/styles/Crossplane/allowed-jargon.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ SCSS
5757
SDK
5858
SDKs
5959
semver
60+
server-side
6061
ServiceAccount
6162
ServiceAccounts
6263
SHA-1

‎utils/vale/styles/Crossplane/crossplane-words.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ XNetwork
5959
xpkg
6060
xpkg.upbound.io
6161
XR
62+
XR's
6263
XRC
6364
XRD
6465
XRD's

0 commit comments

Comments
 (0)