Update formatting

Author: Jefftree

keps/sig-api-machinery/555-server-side-apply/README.md

@@ -322,19 +322,19 @@ _This section must be completed when targeting alpha to a release._
 
 * **Does enabling the feature change any default behavior?**
 
- While this changes how objects are modified and then stored in the database, all the changes should be strictly backward compatible, and shouldn’t break existing automation or users. The increase in size can possibly have adverse, surprising consequences including increased memory usage for controllers, increased bandwidth usage when fetching objects, bigger objects when displaying for users (kubectl get -o yaml). We’re trying to mitigate all of these with the addition of a new header.
+  While this changes how objects are modified and then stored in the database, all the changes should be strictly backward compatible, and shouldn’t break existing automation or users. The increase in size can possibly have adverse, surprising consequences including increased memory usage for controllers, increased bandwidth usage when fetching objects, bigger objects when displaying for users (kubectl get -o yaml). We’re trying to mitigate all of these with the addition of a new header.
 
 * **Can the feature be disabled once it has been enabled (i.e. can we roll back
   the enablement)?**
   Also set `disable-supported` to `true` or `false` in `kep.yaml`.
   Describe the consequences on existing workloads (e.g., if this is a runtime
   feature, can it break the existing applications?).
 
-  Yes. Managed fields will be reset for server-side applied objects.
+  Yes. The consequence is that managed fields will be reset for server-side applied objects (requiring a read/write cycle on the impacted resources).
 
 * **What happens if we reenable the feature if it was previously rolled back?**
 
-The feature will be restored. Server-side applied objects will have lost their “set” which may cause some surprising behavior (fields might not be removed as expected).
+  The feature will be restored. Server-side applied objects will have lost their “set” which may cause some surprising behavior (fields might not be removed as expected).
 
 * **Are there any tests for feature enablement/disablement?**
   The e2e framework does not currently support enabling or disabling feature
@@ -351,15 +351,19 @@ _This section must be completed when targeting beta graduation to a release._
 * **How can a rollout fail? Can it impact already running workloads?**
   Try to be as paranoid as possible - e.g., what if some components will restart
    mid-rollout?
-There is no specific way that the rollout can fail. The rollout can't impact existing workload. 
+There is no specific way that the rollout can fail. The rollout can't impact existing workload.
 * **What specific metrics should inform a rollback?**
 
-The feature shouldn't affect any existing behavior. A surprisingly high number of modification rejections could be a sign that something is not working properly.
+  The feature shouldn't affect any existing behavior. A surprisingly high number of modification rejections could be a sign that something is not working properly.
 
 * **Were upgrade and rollback tested? Was the upgrade->downgrade->upgrade path tested?**
-Because the feature doesn't affect existing behavior, rollback and upgrades haven't be specifically tested.
 
-The new `managedFields` field is cleared when it is incorrect. That protects us from having invalid data inserted by a potential bad upgrade.
+  Because the feature doesn't affect existing behavior, rollback and upgrades haven't be specifically tested.
+The feature is being used by the cluster role aggregator though. Upgrading/downgrading/upgrading, which
+could result in the managedFields being removed, wouldn't cause any problems since the `Rules` field
+filled by the controller is `atomic`, and thus doesn't depend on the current state of the managedFields.
+
+  The new `managedFields` field is cleared when it is incorrect. That protects us from having invalid data inserted by a potential bad upgrade.
 
 * **Is the rollout accompanied by any deprecations and/or removals of features, APIs,
 fields of API types, flags, etc.?** No
@@ -373,9 +377,9 @@ _This section must be completed when targeting beta graduation to a release._
   checking if there are objects with field X set) may be a last resort. Avoid
   logs or events for this purpose.
 
-Any existing metric split by request verb will record the [APPLY](https://github.com/kubernetes/kubernetes/blob/8f6ffb24df989608b87451f89b8ac9fc338ed71c/staging/src/k8s.io/apiserver/pkg/endpoints/metrics/metrics.go#L507-L509) verb if the feature is in use.
+  Any existing metric split by request verb will record the [APPLY](https://github.com/kubernetes/kubernetes/blob/8f6ffb24df989608b87451f89b8ac9fc338ed71c/staging/src/k8s.io/apiserver/pkg/endpoints/metrics/metrics.go#L507-L509) verb if the feature is in use.
 
-Additionally, the OpenAPI spec exposes the available media-type for each individual endpoint. The presence of the `apply` type for the PATCH verb of a endpoints indicates whether the feature is enabled for that specific resource, e.g.
+  Additionally, the OpenAPI spec exposes the available media-type for each individual endpoint. The presence of the `apply` type for the PATCH verb of a endpoints indicates whether the feature is enabled for that specific resource, e.g.
 ```json
 ...
 "patch": {
@@ -388,14 +392,15 @@ Additionally, the OpenAPI spec exposes the available media-type for each individ
     ...
 }
 ...
+```
 
 * **What are the SLIs (Service Level Indicators) an operator can use to determine
 the health of the service?**
 
-There is no specific metric attached to server side apply. All PATCH requests that utilize SSA will use the verb APPLY when logging metrics. API Server metrics that are split by verb automatically include this. They include `apiserver_request_total`, `apiserver_longrunning_gauge`, `apiserver_response_sizes`, `apiserver_request_terminations_total`, `apiserver_selfrequest_total`
+  There is no specific metric attached to server side apply. All PATCH requests that utilize SSA will use the verb APPLY when logging metrics. API Server metrics that are split by verb automatically include this. They include `apiserver_request_total`, `apiserver_longrunning_gauge`, `apiserver_response_sizes`, `apiserver_request_terminations_total`, `apiserver_selfrequest_total`
     - Components exposing the metric: kube-apiserver
-    
-Apply requests (`PATCH` with `application/apply-patch+yaml` mime type) have the same level of SLIs as other types of requests.
+
+  Apply requests (`PATCH` with `application/apply-patch+yaml` mime type) have the same level of SLIs as other types of requests.
 
 * **What are the reasonable SLOs (Service Level Objectives) for the above SLIs?** n/a
 Apply requests (`PATCH` with `application/apply-patch+yaml` mime type) have the same level of SLOs as other types of requests.
@@ -423,7 +428,7 @@ the existing API objects?** Objects applied using server side apply will have th
 operations covered by [existing SLIs/SLOs]?** No
 
 * **Will enabling / using this feature result in non-negligible increase of
-resource usage (CPU, RAM, disk, IO, ...) in any components?** Since objects are larger with the new `managedFields`, caches as well as network bandwidth requirement will increase. 
+resource usage (CPU, RAM, disk, IO, ...) in any components?** Since objects are larger with the new `managedFields`, caches as well as network bandwidth requirement will increase.
 
 ### Troubleshooting
 
@@ -435,7 +440,7 @@ _This section must be completed when targeting beta graduation to a release._
 
 * **How does this feature react if the API server and/or etcd is unavailable?**
 
-The feature is part of of the API server and will not function without it
+  The feature is part of of the API server and will not function without it
 
 * **What are other known failure modes?**
   For each of them, fill in the following information by copying the below template:
@@ -451,9 +456,6 @@ The feature is part of of the API server and will not function without it
 
 * **What steps should be taken if SLOs are not being met to determine the problem?** n/a
 
-[supported limits]: https://git.k8s.io/community//sig-scalability/configs-and-limits/thresholds.md
-[existing SLIs/SLOs]: https://git.k8s.io/community/sig-scalability/slos/slos.md#kubernetes-slisslos
-
 ### Risks and Mitigations
 
 We used a feature branch to ensure that no partial state of this feature would
@@ -529,7 +531,7 @@ updated when we know the concrete things changing for beta.
 A GA version of this is targeted for 1.21.
 
 - E2E tests are created and graduate to conformance
-- [Apply for client-go's typed client](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/2144-clientgo-apply) is implemented and has an in-tree controller using it
+- [Apply for client-go's typed client](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/2144-clientgo-apply) is implemented and at least one kube-controller-manager uses that client
 - Outstanding bugs around status wiping and scale subresource are fixed
 
 ### Upgrade / Downgrade Strategy