kustomize: add deprecation warning to docs

[natasha41575]

Should be merged after release containing the deprecation warnings

/hold
/cc @KnVerey

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: natasha41575

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [natasha41575]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[natasha41575]

/remove-lifecycle rotten

[natasha41575]

I need to update this PR to reflect all the deprecated fields, and change the version number.

[holdeneoneal]

@natasha41575 can you comment on when these features will be removed from kustomize? Is there an issue or milestone for their planned removal? Looking to understand what our runway is to remove these from our code base. Thank you!

[natasha41575]

@holdeneoneal Thank you for the very valid question! In response to your question, I added the answer to the docs in this PR so that it is really clear what the timeline is, which applies to all deprecated fields:

Though this field will never be removed from the current Kustomization v1beta1 API, the field will not be included
in the API for Kustomization v1. When Kustomization v1 is available, we will announce the deprecation of Kustomization v1beta1. There will be at least two releases between deprecation and removal of Kustomization v1beta1.

There is no strict timeline for this, but realistically the removal of these fields will likely take at least a year or two. It is only when we have deprecated Kustomization v1beta1 entirely that we will be in a position to drop support for deprecated fields completely, so you should keep an eye out for that announcement.

[natasha41575]

@KnVerey This is ready for review!

[natasha41575]

/cc @koba1t @annasong20

[natasha41575]

/hold

So that this isn't merged until release

[holdeneoneal]

@holdeneoneal Thank you for the very valid question! In response to your question, I added the answer to the docs in this PR so that it is really clear what the timeline is, which applies to all deprecated fields:

Though this field will never be removed from the current Kustomization v1beta1 API, the field will not be included
in the API for Kustomization v1. When Kustomization v1 is available, we will announce the deprecation of Kustomization v1beta1. There will be at least two releases between deprecation and removal of Kustomization v1beta1.

There is no strict timeline for this, but realistically the removal of these fields will likely take at least a year or two. It is only when we have deprecated Kustomization v1beta1 entirely that we will be in a position to drop support for deprecated fields completely, so you should keep an eye out for that announcement.

Thank you, Natasha! I have a follow up question. When you say "at least two releases", are those minor version releases of kustomize or major version releases?

[natasha41575]

Thank you, Natasha! I have a follow up question. When you say "at least two releases", are those minor version releases of kustomize or major version releases?

Any two releases, I think this includes patch/minor releases. Kustomize is also built into kubectl, so we generally have to follow their deprecation policy: https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli

[koba1t]

Thanks, @natasha41575!
I think this announce is very useful!

So, I think the legacy patches syntax is removed next release.
Could you consider announcing this syntax change?

[KnVerey]

So, I think the kubernetes-sigs/kustomize#4911 syntax is removed next release.
Could you consider announcing this syntax change?

Great point! That syntax is super old and currently nowhere in the docs, but we added its removal to the release notes.

[KnVerey]

A couple copy-paste things to clean up. Should we mention kustomize edit fix for any of these?

[KnVerey]

Suggested change

	The `patchesStrategicMerge` field was deprecated in v5.0.0. The `bases` field was deprecated in v2.1.0. This field will never be removed from the
	The `patchesStrategicMerge` field was deprecated in v5.0.0. This field will never be removed from the

[natasha41575]

🤦‍♀️ Sorry about that, I should be proof reading my own PRs...

[natasha41575]

A couple copy-paste things to clean up. Should we mention kustomize edit fix for any of these?

Done! And added a warning that the automatic vars->replacement conversion may fail.

[natasha41575]

/unhold

[KnVerey]

/lgtm