Skip to content

Commit 8f7c04a

Browse files
JefftreeJefftree
committed
Draft blog post for SSA GA
1 parent a54e81e commit 8f7c04a

File tree

1 file changed

+172
-0
lines changed

1 file changed

+172
-0
lines changed

‎content/en/blog/_posts/2021-07-15-server-side-apply-ga.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
layout: blog
3+
title: "Kubernetes 1.22: Server Side Apply moves to GA"
4+
description: >
5+
Server Side Apply moves to GA.
6+
date: 2021-07-15T10:00:00-08:00
7+
slug: Server-Side-Apply-GA
8+
---
9+
10+
Authors: Jeffrey Ying, Google & Joe Betz, Google
11+
12+
Server-side Apply (SSA) has been promoted to GA in the Kubernetes v1.22 release. Support for Server-side Apply was introduced as alpha in Kubernetes v1.14 release, promoted to beta in the Kubernetes v1.16 release, and [promoted to beta 2](https://kubernetes.io/blog/2020/04/01/kubernetes-1.18-feature-server-side-apply-beta-2/) in the Kubernetes v1.18 release.
13+
14+
The GA milestone indicates that Kubernetes users may depend on the feature and its API without fear of backwards incompatible changes in future causing regressions. GA features are protected by the [Kubernetes deprecation policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/).
15+
16+
What is Server-side Apply?
17+
18+
Server-side Apply helps users and controllers manage their resources through declarative configurations. Server-side Apply replaces the client side apply feature implemented by “kubectl apply” with a server-side implementation, permitting use by tools/clients other than kubectl. To learn more about why Server-side Apply is important, or to learn how to use Server-side Apply from `kubectl`, see the [Beta 2 release announcement](https://kubernetes.io/blog/2020/04/01/kubernetes-1.18-feature-server-side-apply-beta-2/).
19+
20+
What’s new since Beta?
21+
22+
Since the [Beta 2 release](https://kubernetes.io/blog/2020/04/01/kubernetes-1.18-feature-server-side-apply-beta-2/) subresources support has been added, and both client-go and Kubebuilder have added comprehensive support for Server-side Apply. This completes the Server-side Apply functionality required to make controller development practical.
23+
Subresource Support
24+
Server-side Apply now fully supports subresources like status and scale. This is particularly important for controllers, which are often responsible for writing to subresources.
25+
Server-side Apply support in client-go
26+
Previously, Server-side Apply could only be called from the client-go typed client using the `Patch` function, with `PatchType` set to `ApplyPatchType`. Now, `Apply` functions are included in the client to allow for a more direct and typesafe way of calling Server-side Apply. Each `Apply` function takes an "apply configuration" type as an argument, which is a structured representation of an Apply request. For example:
27+
28+
```go
29+
import (
30+
...
31+
v1ac "k8s.io/client-go/applyconfigurations/autoscaling/v1"
32+
)
33+
34+
hpaApplyConfig := v1ac.HorizontalPodAutoscaler(autoscalerName, ns).
35+
WithSpec(v1ac.HorizontalPodAutoscalerSpec().
36+
WithMinReplicas(0)
37+
)
38+
39+
return hpav1client.Apply(ctx, hpaApplyConfig, metav1.ApplyOptions{FieldManager: "mycontroller", Force: true})
40+
```
41+
42+
Note in this example that `HorizontalPodAutoscaler` is imported from an "applyconfigurations" package. Each "apply configuration" type represents the same Kubernetes object kind as the corresponding go struct, but where all fields are pointers to make them optional, allowing apply requests to be accurately represented. For example, this when the apply configuration in the above example is marshalled to YAML, it produces:
43+
44+
```yaml
45+
apiVersion: autoscaling/v1
46+
kind: HorizontalPodAutoscaler
47+
metadata:
48+
name: myHPA
49+
namespace: myNamespace
50+
spec:
51+
minReplicas: 0
52+
```
53+
54+
To understand why this is needed, the above YAML cannot be produced by the v1.HorizontalPodAutoscaler go struct. Take for example:
55+
56+
```go
57+
hpa := v1.HorizontalPodAutoscaler{
58+
TypeMeta: metav1.TypeMeta{
59+
APIVersion: "autoscaling/v1",
60+
Kind: "HorizontalPodAutoscaler",
61+
},
62+
ObjectMeta: ObjectMeta{
63+
Namespace: ns,
64+
Name: autoscalerName,
65+
},
66+
Spec: v1.HorizontalPodAutoscalerSpec{
67+
MinReplicas: pointer.Int32Ptr(0),
68+
},
69+
}
70+
```
71+
72+
The above code attempts to declare the same apply configuration as shown in the previous examples, but when marshalled to YAML, produces:
73+
74+
```yaml
75+
kind: HorizontalPodAutoscaler
76+
apiVersion: autoscaling/v1
77+
metadata
78+
name: myHPA
79+
namespace: myNamespace
80+
creationTimestamp: null
81+
spec:
82+
scaleTargetRef:
83+
kind: ""
84+
name: ""
85+
minReplicas: 0
86+
maxReplicas: 0
87+
```
88+
89+
Which, among other things, contains `spec.maxReplicas` set to `0`. This is almost certainly not what the caller intended (the intended apply configuration says nothing about the `maxReplicas` field), and could have serious consequences on a production system: it directs the autoscaler to downscale to zero pods. The problem here originates from the fact that the go structs contain required fields that are zero valued if not set explicitly. The go structs work as intended for create and update operations, but are fundamentally incompatible with apply, which is why we have introduced the generated "apply configuration" types.
90+
91+
The "apply configurations" also have convenience `With<FieldName>` functions that make it easier to build apply requests. This allows developers to set fields without having to deal with the fact that all the fields in the "apply configuration" types are pointers, and are inconvenient to set using go. For example `MinReplicas: &0` is not legal go code, so without the `With` functions, developers would work around this problem by using a library, .e.g. `MinReplicas: pointer.Int32Ptr(0)`, but string enumerations like `corev1.Protocol` are still a problem since they cannot be supported by a general purpose library. In addition to the convenience, the `With` functions also isolate developers from the underlying representation, which makes it safer for the underlying representation to be changed to support additional features in the future.
92+
How to use Server-side Apply in a controller?
93+
The new client-go support makes it much easier to use Server-side Apply in controllers.
94+
95+
When authoring new controllers to use Server-side Apply, a good approach is to have the controller recreate the apply configuration for an object each time it reconciles that object. This ensures that the controller fully reconciles all the fields that it is responsible for. Controllers typically should unconditionally set all the fields they own by setting `Force: true` in the `ApplyOptions`. Controllers must also provide a `FieldManager` name that is unique to the reconciliation loop that apply is called from.
96+
97+
When upgrading existing controllers to use Server-side Apply the same approach often works well--migrate the controllers to recreate the apply configuration each time it reconciles any object. Unfortunately, the controller might have multiple code paths that update different parts of an object depending on various conditions. Migrating a controller like this to Server-side Apply can be risky because if the controller forgets to include any fields in an apply configuration that is included in a previous apply request, a field can be accidently deleted. To ease this type of migration, client-go apply support provides a way to replace any controller reconciliation code that performs a "read/modify-in-place/update" (or patch) workflow with a "extract/modify-in-place/apply" workflow. Here's an example of the new workflow:
98+
99+
```go
100+
fieldMgr := "my-field-manager"
101+
deploymentClient := clientset.AppsV1().Deployments("default")
102+
103+
// read, could also be read from a shared informer
104+
deployment, err := deploymentClient.Get(ctx, "example-deployment", metav1.GetOptions{})
105+
if err != nil {
106+
// handle error
107+
}
108+
109+
// extract
110+
deploymentApplyConfig, err := appsv1ac.ExtractDeployment(deployment, fieldMgr)
111+
if err != nil {
112+
// handle error
113+
}
114+
115+
// modify-in-place
116+
deploymentApplyConfig.Spec.Template.Spec.WithContainers(corev1ac.Container().
117+
WithName("modify-slice").
118+
WithImage("nginx:1.14.2"),
119+
)
120+
121+
// apply
122+
applied, err := deploymentClient.Apply(ctx, extractedDeployment, metav1.ApplyOptions{FieldManager: fieldMgr})
123+
```
124+
125+
For developers using Custom Resource Definitions (CRDs), the Kubebuilder apply support provides the same capabilities. <TODO: explain how to use Kubebuilder in more detail?>.
126+
How to Use Server-side Apply with CRDs
127+
128+
It is strongly recommended that all CRDs have a schema. Custom Resource Definitions (CRDs) without a schema are treated as unstructured data by Server-side Apply. Keys are treated as fields in a struct and lists are assumed to be atomic.
129+
130+
CRD that specify a schema are able to specify additional annotations in the schema. Please refer to the documentation on the full list of available annotations.
131+
132+
New annotations since beta:
133+
134+
Defaulting: Values for fields that appliers do not express explicit interest in should be defaulted. This prevents an applier from unintentionally owning a defaulted field that might cause conflicts with other appliers. If unspecified, the default value is nil or the nil equivalent for the corresponding type.
135+
136+
- Usage: see the [Defaulting Documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#defaulting) for more details.
137+
- Golang: `+default=<value>`,
138+
- OpenAPI extension: `default: <value>`
139+
140+
141+
Atomic for maps and structs:
142+
143+
Maps: By default maps are granular. A different manager is able to manage each map entry. They can also be configured to be atomic such that a single manager owns the entire map.
144+
145+
- Usage: Refer to [Merge Strategy](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy) for a more detailed overview
146+
- Golang: `+mapType=granular/atomic`
147+
- OpenAPI extension: x-kubernetes-map-type: granular/atomic`
148+
149+
Structs: By default structs are granular and a separate applier may own each field. For certain kinds of structs, atomicity may be desired. This is most commonly seen in small coordinate-like structs such as Field/Object/Namespace Selectors, Object References, RGB values, Endpoints (Protocol/Port pairs), etc.
150+
151+
- Usage: Refer to [Merge Strategy](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy) for a more detailed overview
152+
- Golang: `+structType=granular/atomic`
153+
- OpenAPI extension: `x-kubernetes-map-type:atomic/granular`
154+
155+
What's Next?
156+
157+
<TODO: jpbetz: explain WG API expression's future a bit?>
158+
How to get involved?
159+
The working-group for apply is available on slack #wg-api-expression, through the mailing list and we also meet every other Tuesday at 9.30 PT on Zoom.
160+
161+
We would also like to use the opportunity to thank the hard work of all the contributors involved in making this promotion to GA possible:
162+
163+
- Andrea Nodari
164+
- Antoine Pelisse
165+
- Daniel Smith
166+
- Jeffrey Ying
167+
- Jenny Buckley
168+
- Joe Betz
169+
- Julian Modesto
170+
- Kevin Delgado
171+
- Kevin Wiesmüller
172+
- Maria Ntalla

0 commit comments

Comments
 (0)