kubectl apply umbrella issue

[bgrant0607]

See #35234 for work items

---

Apply Details

---

To capture discussion on #1178, #1702, #13007, #17333, and other issues/PRs.
cc @jackgr @ghodss

Summary (to be transcribed into a doc):

Apply conceptually is intended to enable users to just specify a configuration and "make it so". But it's not that easy.

We represent default values explicitly in the API so that system components, ecosystem components, tools, and users don't need to reason about implicit behaviors, especially since such behaviors can change across API versions.
https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#defaulting

We also want apply to work with automation, such as auto-scaling, and asynchronously filled-in values, such as node or IP assignments.
https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#late-initialization

Therefore, unspecified values are (supposed to be) interpreted by apply as not managed by the user.

To do this, apply is implemented as a kind of 3-way merge, of their previous configuration, their new configuration, and the live state in apiserver/etcd. Obviously, this means that the previous configuration needs to be stored somewhere. It is currently stored in an annotation on each resource (#16543).

The diff-and-patch process has a few tricky issues. One is that we often don't want to overwrite arrays, which is standard json patch behavior, and we don't want to merge elements positionally, either. Many arrays have primary keys, similar to maps. We created a custom patch strategy to implement this behavior:
https://github.com/kubernetes/kubernetes/blob/master/docs/devel/api-conventions.md#strategic-merge-patch

One problem we haven't solved yet is that OneOf / union cases also need to be recognized, so that the previous value can be automatically nulled when a selection is changed (example of a OneOf issue: #24198).

We need to find a way to represent the merge strategy, merge keys, and OneOf relationships in Swagger (probably Swagger 2.0), as well. Otherwise, kubectl apply won't work properly with a cluster of a different release.

We need to clean up all cases in the API types.go files that don't properly allow us to distinguish unspecified values from default values (e.g., using pointers for optional fields).

We should ensure imperative mutations like scale, label, and annotate don't update the last-applied-configuration annotation by default, since that would cause those changes to get removed on the next apply if not added to the user's configuration file.

The user needs to be able to explicitly nil values when performing apply (so that needs to be fixed if it doesn't work).

We should detect conflicts between the live state and the applied state (#13576).

We should fix the handling of secret data (#23564, #20508).

We need a pattern to recommend for rolling out ConfigMaps (#22368). (I think changing the name of the ConfigMap should just work, once we have server-side cascading deletion.)

We should figure out how to automatically test apply #26234.

Search issues for "kubectl apply" to find other misc. bugs and features.

cc @adohe @ghodss @kubernetes/kubectl

[bgrant0607]

ObjectMeta.CreationTimestamp should be a pointer, for example.

[adohe]

@bgrant0607 Thanks very much :) I will look at this carefully.

[bgrant0607]

TPR support: #29542

[mengqiy]

I think we should also include #34292 in this kubectl apply umbrella issue

[pwittrock]

FYI I moved the issue tracking list to #35234 because I found that when I edit the description of this issue it appears as coming from @bgrant0607 which was surprising to me and not my intention.

[fabianofranz]

@pwittrock can this one be closed?

[pwittrock]

Closed in favor of #35234 to track the remaining work items.

[bgrant0607]

@pwittrock Has the apply design, described in this issue, been documented anywhere?

[pwittrock]

@bgrant0607 Not yet, but it is something I am working on. I have 5 PRs planned for kubectl.

1. Overview of commands vs basic resource config vs resource config with apply. Sent for review in kubernetes/website#2274
2. In depth explanation of commands
3. In depth explanation of basic resource config
4. In depth explanation of resource config with apply

• Includes elements of apply design

5. Several kubectl tasks used with the above commands: seeding configs by forking a repo, seeding configs using kubectl create deployment --image nginx nginx -o yaml --dry-run > nginx_deployment.yaml