Skip to content

Commit

Permalink
ssa: Make everything consistent into "Server-Side Apply"
Browse files Browse the repository at this point in the history
  • Loading branch information
apelisse committed Aug 25, 2022
1 parent dda09b0 commit c99d63f
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions content/en/docs/reference/using-api/server-side-apply.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ min-kubernetes-server-version: 1.16

## Introduction

Server Side Apply helps users and controllers manage their resources through
Server-Side Apply helps users and controllers manage their resources through
declarative configurations. Clients can create and modify their
[objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/)
declaratively by sending their fully specified intent.
Expand All @@ -42,26 +42,26 @@ field. If the field is not owned by any other field managers, it is either
deleted from the live object or reset to its default value, if it has one. The
same rule applies to associative list or map items.

Server side apply is meant both as a replacement for the original `kubectl
Server-Side Apply is meant both as a replacement for the original `kubectl
apply` and as a simpler mechanism for controllers to enact their changes.

If you have Server Side Apply enabled, the control plane tracks managed fields
If you have Server-Side Apply enabled, the control plane tracks managed fields
for all newly created objects.

## Field Management

Compared to the `last-applied` annotation managed by `kubectl`, Server Side
Apply uses a more declarative approach, which tracks a user's field management,
rather than a user's last applied state. This means that as a side effect of
using Server Side Apply, information about which field manager manages each
using Server-Side Apply, information about which field manager manages each
field in an object also becomes available.

For a user to manage a field, in the Server Side Apply sense, means that the
For a user to manage a field, in the Server-Side Apply sense, means that the
user relies on and expects the value of the field not to change. The user who
last made an assertion about the value of a field will be recorded as the
current field manager. This can be done either by changing the value with
`POST`, `PUT`, or non-apply `PATCH`, or by including the field in a config sent
to the Server Side Apply endpoint. When using Server-Side Apply, trying to
to the Server-Side Apply endpoint. When using Server-Side Apply, trying to
change a field which is managed by someone else will result in a rejected
request (if not forced, see [Conflicts](#conflicts)).

Expand All @@ -73,7 +73,7 @@ of a field by removing it from their configuration.
Field management is stored in a`managedFields` field that is part of an object's
[`metadata`](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta).

A simple example of an object created by Server Side Apply could look like this:
A simple example of an object created by Server-Side Apply could look like this:

```yaml
apiVersion: v1
Expand Down Expand Up @@ -207,12 +207,12 @@ would have failed due to conflicting ownership.

## Merge strategy

The merging strategy, implemented with Server Side Apply, provides a generally
more stable object lifecycle. Server Side Apply tries to merge fields based on
The merging strategy, implemented with Server-Side Apply, provides a generally
more stable object lifecycle. Server-Side Apply tries to merge fields based on
the actor who manages them instead of overruling based on values. This way
multiple actors can update the same object without causing unexpected interference.

When a user sends a "fully-specified intent" object to the Server Side Apply
When a user sends a "fully-specified intent" object to the Server-Side Apply
endpoint, the server merges it with the live object favoring the value in the
applied config if it is specified in both places. If the set of items present in
the applied config is not a superset of the items applied by the same user last
Expand Down Expand Up @@ -294,7 +294,7 @@ manager can then modify or delete those fields without conflict.

## Custom Resources

By default, Server Side Apply treats custom resources as unstructured data. All
By default, Server-Side Apply treats custom resources as unstructured data. All
keys are treated the same as struct fields, and all lists are considered atomic.

If the Custom Resource Definition defines a
Expand All @@ -321,7 +321,7 @@ might not be able to resolve or act on these conflicts.
## Transferring Ownership

In addition to the concurrency controls provided by [conflict resolution](#conflicts),
Server Side Apply provides ways to perform coordinated
Server-Side Apply provides ways to perform coordinated
field ownership transfers from users to controllers.

This is best explained by example. Let's look at how to safely transfer
Expand All @@ -333,7 +333,7 @@ Say a user has defined deployment with `replicas` set to the desired value:

{{< codenew file="application/ssa/nginx-deployment.yaml" >}}

And the user has created the deployment using server side apply like so:
And the user has created the deployment using Server-Side Apply like so:

```shell
kubectl apply -f https://k8s.io/examples/application/ssa/nginx-deployment.yaml --server-side
Expand Down Expand Up @@ -410,7 +410,7 @@ applier has no way of knowing whether their next apply will overwrite other
users' changes.

Another difference is that an applier using Client Side Apply is unable to
change the API version they are using, but Server Side Apply supports this use
change the API version they are using, but Server-Side Apply supports this use
case.

## Upgrading from client-side apply to server-side apply
Expand Down Expand Up @@ -464,7 +464,7 @@ kubectl apply --server-side --field-manager=my-manager [--dry-run=server]

## API Endpoint

With the Server Side Apply feature enabled, the `PATCH` endpoint accepts the
With the Server-Side Apply feature enabled, the `PATCH` endpoint accepts the
additional `application/apply-patch+yaml` content type. Users of Server Side
Apply can send partially specified objects as YAML to this endpoint. When
applying a configuration, one should always include all the fields that they
Expand Down Expand Up @@ -510,7 +510,7 @@ applier takes ownership of any fields updated in the same request.

## Disabling the feature

Server Side Apply is a beta feature, so it is enabled by default. To turn this
Server-Side Apply is a beta feature, so it is enabled by default. To turn this
[feature gate](/docs/reference/command-line-tools-reference/feature-gates) off,
you need to include the `--feature-gates ServerSideApply=false` flag when
starting `kube-apiserver`. If you have multiple `kube-apiserver` replicas, all
Expand Down

0 comments on commit c99d63f

Please sign in to comment.