From bfcaa3dd55c7f7c8e98c9775dfd12fbb49d514aa Mon Sep 17 00:00:00 2001 From: joshvanl Date: Mon, 31 Jan 2022 13:42:50 +0000 Subject: [PATCH] Change `APPLY`->`Apply`, `Server Side`->`Server-Side` Signed-off-by: joshvanl --- design/20220118.server-side-apply.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/design/20220118.server-side-apply.md b/design/20220118.server-side-apply.md index 74bbbfb72..e78fc494b 100644 --- a/design/20220118.server-side-apply.md +++ b/design/20220118.server-side-apply.md @@ -1,5 +1,5 @@ --- -title: Server Side Apply +title: Server-Side Apply authors: - "@joshvanl" reviewers: @@ -12,7 +12,7 @@ last-updated: 2022-01-18 status: implementable --- -# Server Side Apply +# Server-Side Apply ## Table of Contents @@ -36,7 +36,7 @@ status: implementable ## Summary -Server Side Apply is a [Kubernetes +Server-Side Apply is a [Kubernetes feature](https://kubernetes.io/docs/reference/using-api/server-side-apply/) whereby clients writing to a resource that is managed by more than one client can @@ -45,7 +45,7 @@ can - make decisions on what to do if there is a conflict with another client on what a field value should be. -Server Side Apply works by the client sending a PATCH API request with a +Server-Side Apply works by the client sending a PATCH API request with a `Content-Type` header with the value `application/apply-patch+yaml`. The `fieldManager=` URL query can be optionally sent which instructs which field manager to use (or alternatively, will be derived from the @@ -55,7 +55,7 @@ managed fields which are omitted) as they appear in the body. A client's managed fields are defined as the fields that are labelled with the client's manager name `` (or client's user agent equivalent). -Server Side Apply is is useful for cert-manager for 2 reasons: +Server-Side Apply is is useful for cert-manager for 2 reasons: ### Conflicts @@ -68,7 +68,7 @@ controller, slowing cert-manager down. ### Deleting Fields -Without Server Side Apply, it is difficult for cert-manager to reason about some +Without Server-Side Apply, it is difficult for cert-manager to reason about some fields that should be _deleted_ on an UPDATE operation during reconciliation. One such example are Certificate SecretTemplate's Annotations and Labels. If a key was removed from either the Annotation or Label field on the SecretTemplate, @@ -156,7 +156,7 @@ cert-manager-certificates-issuing/v1.7.0 (Linux/amd64) cert-manager/0b686b8f38c8 ### API Call Code Changes All CREATE and UPDATE operations in cert-manager controllers are to be replaced -with APPLY. For this change, controllers will need to be modified so that for +with Apply. For this change, controllers will need to be modified so that for these calls, _only_ the fields in which they manage should be included in the PATCH API call. This means each controller will need to define exactly which fields they are concerned with. A package will be created which all API calls @@ -175,7 +175,7 @@ fields, such as the Issuing Condition, may have an undefined number of potential managers (both internal and external to the cert-manager controller), using the same manager for things is not a possibility. You can read more about the `force` paramerter on the Kubernetes documentation on -[Server Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/), +[Server-Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/), and in particular the [Conflicts](https://kubernetes.io/docs/reference/using-api/server-side-apply/#conflicts) section. @@ -186,7 +186,7 @@ manage the same fields should never be writing to the same field at the same time (as they should be gated by those or other fields presence and values, such as the Issuing condition for the issuing and trigger controllers). -There is likely no APPLY call that cert-manager does not set the `force` +There is likely no Apply call that cert-manager does not set the `force` parameter to true since it, [never wants to give up ownership claim, and always wants to overwrite values](https://kubernetes.io/docs/reference/using-api/server-side-apply/#conflicts). @@ -196,7 +196,7 @@ See ### client-go Testing The [fake client-go client](https://github.com/kubernetes/client-go/issues/970) -does not support the Apply patch call for mocking API calls and events. This +does not support the Apply PATCH call for mocking API calls and events. This means that significant controller unit-testing will either need to moved to testing against a real API server as integration tests, the controller [test framework must add custom support for Apply](https://github.com/jetstack/cert-manager/blob/master/pkg/controller/test/context_builder.go), @@ -206,7 +206,7 @@ will take time to be released so a stop gap would always be needed. ### API Changes Some API fields will need to have some metadata updated to function better under -Server Side Apply. One such example is adding `x-kubernetes-list-type=map` and +Server-Side Apply. One such example is adding `x-kubernetes-list-type=map` and `x-kubernetes-list-map-keys=Type` to the [Certificates Status Condition slice](https://github.com/jetstack/cert-manager/blob/0ca1ce9a6a1d7c311afd4b3e786975759249132a/pkg/apis/certmanager/v1/types_certificate.go#L385), so that controllers are able to apply distinct condition types, without @@ -216,13 +216,13 @@ these API type tags correctly. ## Feature Gate -Placing the APPLY functionality behind a feature gate should be required. +Placing the Apply functionality behind a feature gate should be required. Placing this functionality behind a feature gate would allow the cert-manager authors gain confidence about its correctness, and ensure there are no regressions in the stability of controller reconciliation. -To reach graduation, the cert-manager authors should consider the server side -apply implementation for cert-manager to be safe for end users. One strategy for +To reach graduation, the cert-manager authors should consider the Server-Side +Apply implementation for cert-manager to be safe for end users. One strategy for gaining confidence that it is a safe change is to solicit feedback from end users who have the feature enabled. Graduation should ideally be done over no more than one or two releases, however the project shouldn't proceed with