Some changes #1

jennybuckley · 2019-03-12T20:16:37Z

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please delete this note before submitting the pull request.

For 1.14 Features: set Milestone to 1.14 and Base Branch to dev-1.14

For Chinese localization, base branch to release-1.12

For Korean Localization: set Base Branch to dev-1.13-ko.

Help editing and submitting pull requests:
https://kubernetes.io/docs/contribute/start/#improve-existing-content.

Help choosing which branch to use:
https://kubernetes.io/docs/contribute/start#choose-which-git-branch-to-use.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

apelisse · 2019-03-12T20:29:32Z

content/en/docs/reference/using-api/api-concepts.md

@@ -319,21 +319,24 @@ Some values of an object are typically generated before the object is persisted.

 ## Server Side Apply

-Server Side Apply (SSA) is offering an apply path on the apiserver side of kubernetes instead of the previous/current Client Side Apply (CSA) that happens in kubectl.
+{{< feature-state for_k8s_version="v1.14" state="alpha" >}} In vesion 1.14, if the Server Side Apply feature is enabled, The `PATCH` endpoint will accept the additional `application/apply-patch+yaml` content type. 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.


In vesion 1.14
:-)

I find it surprising that this section starts with a super technical explanation? Should we at least introduce somehow?

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.

Maybe a variation of this sentence should go first?

Sure I agree.

apelisse · 2019-03-12T20:31:11Z

content/en/docs/reference/using-api/api-concepts.md


-*Note:* This is an alpha feature and needs to be enabled by setting the related (Feature Gate)[docs/reference/command-line-tools-reference/feature-gates.md].
+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 field in an object becomes available.


I don't know if I'd compare it directly to what we had before? Though it might be useful for some people

Assuming we start the section with

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.

then it makes sense to me to say how our approach is conceptually different

apelisse · 2019-03-12T21:12:24Z

content/en/docs/reference/using-api/api-concepts.md

-A conflict is a special status error that occurs when an `Apply` operation tries to change a field, which another user also claims to manage.
+A conflict is a special status error that occurs when an `Apply` operation tries to change a field, which another user also claims to manage. This will prevent an applier from unintentionally overwriting the value set by another user. When this occurs, the applier has 3 options to resolve the conflicts:
+
+* If overwriting the value was intentional (or if the applier is an automated process like a controller) the applier should set the `force` query parameter to true and make the request again. This will force the operation to succeed and the field will be removed all other field managers that claimed to manage it.


I'm not completely sure what's going to happen when you say "This will force the operation to succeed and the field will be removed all other field managers that claimed to manage it."

Ah yeah, that is kind of ambiguous

kwiesmueller

Small typo, aside from that feel free to merge

kwiesmueller · 2019-03-12T22:47:21Z

content/en/docs/reference/using-api/api-concepts.md


-#### Comparison with CSA
+When an 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 the applied by the same user last time, each missing item that is not managed by any other field manager is removed.


the items the applied by the same user last time,

apelisse

Do we need somewhere to explain that we support multiple versions, and that we convert objects across version to detect conflict?

apelisse · 2019-03-12T22:53:11Z

content/en/docs/reference/using-api/api-concepts.md


-#### Kubectl
+* **Overwrite value, become sole manager:** If overwriting the value was intentional (or if the applier is an automated process like a controller) the applier should set the `force` query parameter to true and make the request again. This will force the operation to succeed, change the value of the field, and remove the field from all other managers' entries in managedFields.


I really like this list

kwiesmueller · 2019-03-12T22:56:34Z

Not sure how far this should go for alpha, but I guess a deeper explanation on how it works internally would be good at some point.
Maybe also how maps and lists get treated when merging etc.

And I wanted to do examples in the respective Kubectl docs.

jennybuckley · 2019-03-12T23:21:26Z

@kwiesmueller Thanks for reviewing, yes I think we should at some point include how maps, lists, atomic stuff, etc get treated when merging, openapi extensions this uses to make those decisions, maybe a high level description of exactly what happens from when a user makes an apply request to when they get a response, and maybe a description of the format of metav1.Fields like the one in types.go. Not sure how many of these we need for alpha docs.

And we definitely need kubectl examples as well, but I think they don't belong in this api documentation (I could also be wrong).

Also I don't think I have permission to merge this, since it's to your fork of the website repo.

kwiesmueller · 2019-03-13T06:45:00Z

I sent you both invites to my fork @jennybuckley so it should be possible in theory. But merged anyways.

Where do you think those examples should go? Isn't there a section in this repo for it?

apelisse reviewed Mar 12, 2019

View reviewed changes

jennybuckley force-pushed the patch-1 branch from 4f5f29b to 03ed7f6 Compare March 12, 2019 22:19

jennybuckley mentioned this pull request Mar 12, 2019

start serverside-apply documentation kubernetes/website#13077

Merged

kwiesmueller approved these changes Mar 12, 2019

View reviewed changes

apelisse reviewed Mar 12, 2019

View reviewed changes

jennybuckley force-pushed the patch-1 branch from 03ed7f6 to 98fc96c Compare March 12, 2019 22:53

Update api concepts

df218ed

jennybuckley force-pushed the patch-1 branch from 98fc96c to df218ed Compare March 12, 2019 23:08

kwiesmueller merged commit 32f1c95 into kwiesmueller:serverside-apply-docs Mar 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Some changes #1

Some changes #1

jennybuckley commented Mar 12, 2019

apelisse Mar 12, 2019

apelisse Mar 12, 2019

apelisse Mar 12, 2019

jennybuckley Mar 12, 2019

apelisse Mar 12, 2019

jennybuckley Mar 12, 2019

apelisse Mar 12, 2019

jennybuckley Mar 12, 2019

kwiesmueller left a comment

kwiesmueller Mar 12, 2019

apelisse left a comment

apelisse Mar 12, 2019

kwiesmueller commented Mar 12, 2019

jennybuckley commented Mar 12, 2019 •

edited

Loading

kwiesmueller commented Mar 13, 2019


		Note: This is an alpha feature and needs to be enabled by setting the related (Feature Gate)[docs/reference/command-line-tools-reference/feature-gates.md].
		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 field in an object becomes available.


		#### Comparison with CSA
		When an 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 the applied by the same user last time, each missing item that is not managed by any other field manager is removed.


		#### Kubectl
		* Overwrite value, become sole manager: If overwriting the value was intentional (or if the applier is an automated process like a controller) the applier should set the `force` query parameter to true and make the request again. This will force the operation to succeed, change the value of the field, and remove the field from all other managers' entries in managedFields.

Some changes #1

Some changes #1

Conversation

jennybuckley commented Mar 12, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwiesmueller left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

apelisse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwiesmueller commented Mar 12, 2019

jennybuckley commented Mar 12, 2019 • edited Loading

kwiesmueller commented Mar 13, 2019

jennybuckley commented Mar 12, 2019 •

edited

Loading