/cc @eddiezane

/assign @brianpursley @eddiezane
do you have time to take a look？
No behavior change.

Prune cane be kind of tricky.

Apply, with -n but without --prune, does create resources, but ignores the namespace:

$ kubectl apply -n foo -f prunetest/
clusterrole.rbac.authorization.k8s.io/secret-reader created

I don't know how --prune should work in this case.

• On one hand, it seems like it should work the same way as apply without --prune.
• But on the other hand, it can be surprising if your prune unintentionally matches a label on a non-namespaced resource.

I am inclined to approve this, even though it is inconsistent with how apply without prune works, but I want to see what @seans3 thinks first.

Another thing to keep in mind is that this issue/PR is framed around the default allow list, which the user can override with --prune-whitelist=. In my experience, the defaults are terrible (including for the unpredictable scoping issue reflected here!), so it's best to always override with exactly what you want. For example, Krane uses pruning under the hood but builds its own allowlist that is restricted to either namespaced or non-namespaced only and that includes CR types (slow and tedious, but behaves predictably).

Point being, we should consider the case where the user is explicitly overriding the list. As @brianpursley rightly points out, a single apply can target namespaced and non-namespaced resources at the same time, even with the --namespace flag. So if the user does kubectl apply --prune -n test --prune-whitelist= v1/PersistentVolume,my.co/MyGlobalKind, I don't think it would be a good experience for the PVs and MyGlobalKinds to be silently skipped.

Maybe another option could be to change the default allow list when the namespace flag is set, but continue to honor any user-specified list. Wdyt?

I'd also be curious to get other SIG members' perspective on whether we need a notice period for a behaviour change like this, e.g. emit a warning for N releases before making the change. It's true that pruning is marked as alpha in the docs, but that status isn't explicit in the actual command/flag, and this behaviour has been around a VERY long time. So long that someone somewhere likely relies on it, sensibly or not.

Point being, we should consider the case where the user is explicitly overriding the list. As @brianpursley rightly points out, a single apply can target namespaced and non-namespaced resources at the same time, even with the --namespace flag. So if the user does kubectl apply --prune -n test --prune-whitelist= v1/PersistentVolume,my.co/MyGlobalKind, I don't think it would be a good experience for the PVs and MyGlobalKinds to be silently skipped.

Maybe another option could be to change the default allow list when the namespace flag is set, but continue to honor any user-specified list. Wdyt?

Good Point. The current fix is a behavior change and is not consistent with apply without --prune.

Two key problems here.

1. the default whitelist for prune is including so much
2. if a user specifies the kind, it is odd to not cover them

The current fix seems to be easier to understand, but cannot cover the above two problems gracefully.

I'd also be curious to get other SIG members' perspective on whether we need a notice period for a behaviour change like this, e.g. emit a warning for N releases before making the change. It's true that pruning is marked as alpha in the docs, but that status isn't explicit in the actual command/flag, and this behaviour has been around a VERY long time. So long that someone somewhere likely relies on it, sensibly or not.

We should decide which is the final behavior first. Should we ignore the non-namespaced resources finally. Or just warn the user if the flags are not that proper.

A proposal:

In this v1.26(for instance)

1. apply -n xxx without --prune: if there are some non-namespaced resources, give it a warning message.
2. apply -n xxx with --prune: give a warning if there is non-namespaced resources in the allowlist.

In this v1.28+(for instance) if this behavior change is not expected, just add some warning may help.

1. apply -n xxx without --prune: if there are some non-namespaced resources, give it a warning message. (Keep the behavior)
2. apply -n xxx with --prune: skip non-namespaced resources in the allowlist.

As much as I personally don't like the idea of mixing scopes in a single apply operation, from an ecosystem perspective, I think that we should not change or warn based on anything the user is doing explicitly. So if they do apply -n xxx without --prune, and they pass non-namespaced resources, we should continue to handle them without warning. Same if they explicitly give us a prune allow list with a mix of scopes. The problem that I think is worth addressing is specifically the default allow list for apply -n xxx --prune, since that default list is unexpectedly not sensitive to the -n argument, such that it has what users might reasonably perceive to be a bug or dangerous side-effect. Counter-proposal:

In the next release: apply -n xxx --prune emits a warning IFF it is NOT given --prune-whitelist. The warning should say something like "Deprecated: kubectl apply will no longer prune non-namespaced resources by default when used with the --namespace flag in a future release. To preserve the current behaviour, list the resources you want to target explicitly in the --prune-whitelist flag." Possibly, we could also emit a tailored warning for every pruned resource that will be skipped in the future (but that can't be the only warning, because users who happen to not prune anything on a given instance of an apply command may still have that same command affected in the future).

After deprecation period passes: Change the default allow list for apply -n xxx --prune to depend on whether --namespace is set. If it is set, the allow list should only include namespaced resources. If --prune-whitelist is set, there should be no behaviour change.

I personally would support that, but based on #109705 (comment) I suspect Sean may not. No matter what, this PR is proposing a behaviour change to a long-standing command, so a compelling argument for it needs to be brought to the SIG for discussion.

Incidentally, regardless of this decision, IMO we should add an alias for this flag that uses inclusive language, i.e. --prune-allowlist. It would be best to do that ahead of other changes we make (if any) so that the deprecation message calls out the new name.

In the next release: apply -n xxx --prune emits a warning IFF it is NOT given --prune-whitelist. The warning should say something like "Deprecated: kubectl apply will no longer prune non-namespaced resources by default when used with the --namespace flag in a future release. To preserve the current behaviour, list the resources you want to target explicitly in the --prune-whitelist flag." Possibly, we could also emit a tailored warning for every pruned resource that will be skipped in the future (but that can't be the only warning, because users who happen to not prune anything on a given instance of an apply command may still have that same command affected in the future).

After deprecation period passes: Change the default allow list for apply -n xxx --prune to depend on whether --namespace is set. If it is set, the allow list should only include namespaced resources. If --prune-whitelist is set, there should be no behaviour change.

It sounds better to me.

1. apply -n xxx --prune: default prune-whitelist should not include non-namespaced resources. Only ns and pv will be affected. @seans3 (Removing namespace and pv are something dangerous to users.)
2. apply --prune without -n xx: default prune-whitelist should include non-namespaced resources.

There is a discussion in the sig-cli meeting about this at https://www.youtube.com/watch?v=ZGKfwWof9js.

/hold
As this is an api-change, sig will not accept the change.
Re-design may be needed if we want users to have a better experience.

Latest changes look good. A few things about the PR itself:

• The title probably needs to be updated to reflect that this is just a warning.
• It also probably shouldn't say it "Fixes # 110905" because that will close the issue. It is related to that but doesn't fix it yet.
• Can you squash your commits
  I will defer to @KnVerey in case she has other comments

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brianpursley, pacoxu

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Latest changes look good. A few things about the PR itself:

• The title probably needs to be updated to reflect that this is just a warning.
• It also probably shouldn't say it "Fixes # 110905" because that will close the issue. It is related to that but doesn't fix it yet.
• Can you squash your commits
  I will defer to @KnVerey in case she has other comments

Updated and also the release note to use allowlist instead of whitelist.

/lgtm

@KnVerey a go format verify failed and pushed again and need LGTM

/lgtm

This change is confusing and the warning is totally obscure.

For example I use Cuber to compile and apply this YML file:
https://github.com/cuber-cloud/cuber-gem/blob/master/lib/cuber/templates/deployment.yml.erb

That YML file contains everything that goes into the namespace.

Then I apply it to Kubernetes using --prune:
https://github.com/cuber-cloud/cuber-gem/blob/5f4a708bc511c44514129185226db139807cdd8d/lib/cuber/commands/deploy.rb#L86

Why do I get this warning now?

W0723 20:57:03.499655    2113 prune.go:71] Deprecated: kubectl apply will no longer prune non-namespaced resources by default when used with the --namespace flag in a future release. To preserve the current behaviour, list the resources you want to target explicitly in the --prune-allowlist flag.

What should I do? I simply want to apply that YML file to the namespace and prune every resource in the namespace that is no longer present in the YML file.

@collimarco in your provide yaml, the only non-namespaced resource is the namespace itself.

I think this warning will not affect your application.

You have specified the namespace here, and even if you remove the namespace object in the yaml, the apply --prune -n app will not remove the namespace resource in the future version.

• In the current and old versions, if you remove the namespace part in your yaml, and run the apply --prune -n app, then the app namespace will be removed. (This is very dangerous. We just want to avoid it happening in the future.)

You can see an example in #110905.

@pacoxu Perfect, thanks for the clarification. Is there any way to get rid of the warning message? Or will it disappear automatically in the future releases of kubectl?

Is there any way to get rid of the warning message? Or will it disappear automatically in the future releases of kubectl?

We plan to remove the warning in v1.29, and I think the behavior will change in v1.29. But it is still a plan and it should be done with the agreement of SIG-Cli maintainers.