Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

server side apply followup #13321

Merged
merged 2 commits into from
Mar 23, 2019
Merged

server side apply followup #13321

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ace0f2d
change some parts of serverside apply docs in response to comments
Mar 20, 2019
8ad6738
fix typos and wording
Mar 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions content/en/docs/reference/using-api/api-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,12 +319,12 @@ Some values of an object are typically generated before the object is persisted.

## Server Side Apply

{{< feature-state for_k8s_version="v1.14" state="alpha" >}} Server Side Apply allows clients other than kubectl to perform the Apply operation, and will eventually fully replace the complicated Client Side Apply logic that only exists in kubectl. If the Server Side Apply feature is enabled, The `PATCH` endpoint accepts the additional `application/apply-patch+yaml` content type. Users of Server Side Apply can send partially specified objects to this endpoint. An applied config should always include every field that the applier has an opinion about.
{{< feature-state for_k8s_version="v1.14" state="alpha" >}} Server Side Apply allows clients other than kubectl to perform the Apply operation, and will eventually fully replace the complicated Client Side Apply logic that only exists in kubectl. If the Server Side Apply feature is enabled, the `PATCH` endpoint accepts the additional `application/apply-patch+yaml` content type. Users of Server Side Apply can send partially specified objects to this endpoint. An applied config should always include every field that the applier has an opinion about.

### Enable the Server Side Apply alpha feature

Server Side Apply is an alpha feature, so it is disabled by default. To turn this [feature gate](/docs/reference/command-line-tools-reference/feature-gates) on,
you need to include in the `--feature-gates ServerSideApply=true` flag when starting `kube-apiserver`.
you need to include the `--feature-gates ServerSideApply=true` flag when starting `kube-apiserver`.
If you have multiple `kube-apiserver` replicas, all should have the same flag setting.

### Field Management
Expand Down Expand Up @@ -363,6 +363,8 @@ The above object contains a single manager in `metadata.managedFields`. The mana

{{< note >}} This field is managed by the apiserver and should not be changed by the user. {{< /note >}}

Nevertheless it is possible to change `metadata.managedFields` through an `Update` operation. Doing so is highly discouraged, but might be a reasonable option to try if, for example, the `managedFields` get into an inconsistent state (which clearly should not happen).

### Operations

The two operation types considered by this feature are `Apply` (`PATCH` with content type `application/apply-patch+yaml`) and `Update` (all other operations which modify the object). Both operations update the `managedFields`, but behave a little differently.
Expand Down Expand Up @@ -401,9 +403,13 @@ data:
In this example, a second operation was run as an `Update` by the manager called `kube-controller-manager`. The update changed a value in the data field which caused the field's management to change to the `kube-controller-manager`.
{{< note >}}If this update would have been an `Apply` operation, the operation would have failed due to conflicting ownership.{{< /note >}}

### Merge Rules
### 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 fact who manages them instead of overruling just based on values.
This way it is intended to make it easier and more stable for multiple actors updating the same object by causing less unexpected interference.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there is still time, a few nits:
line 322: Change The to the: If the Server Side Apply feature is enabled, The PATCH endpoint ...
line 327: remove: in or change the wording around feature-gates flag: ... you need to include in the --feature-gates ServerSideApply=true flag
line 408: Change:
The merging strategy, implemented with Server Side Apply, provides a generally more stable object lifecycle.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @kbhawkey!
Done.


When a user sends a partially specified 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 twice. If the set of items present in the applied config is not a superset of the items applied by the same user last time, each missing item not managed by any other field manager is removed. For more information about how an object's schema is used to make decisions when merging, see [sigs.k8s.io/structured-merge-diff](https://sigs.k8s.io/structured-merge-diff).
When a user sends a partially specified 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 time, each missing item not managed by any other field manager is removed. For more information about how an object's schema is used to make decisions when merging, see [sigs.k8s.io/structured-merge-diff](https://sigs.k8s.io/structured-merge-diff).

### Conflicts

Expand Down