Better document field/feature availability across Kustomize versions

[yuwenma]

From 2021 Q3/4 roadmap, kustomize will deprecate a list of features including vars, crds, configurations, and potentially some plugin functions. Customers may want to have a clear idea about which and when a function would be deprecated and how to migrate to the new format.

To keep the users in the loop and gather real-time feedback, it's nice to have a deprecation policy doc (aligned with the kubernetes 1 year deprecation policy?), and track the timeline in a centralized place (suggest under the root/README.md) rather than under its own issue.

[k8s-ci-robot]

@yuwenma: This issue is currently awaiting triage.

SIG CLI takes a lead on issue triage for this repo, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[yuwenma]

@monopole @KnVerey @natasha41575 Thoughts?

[mikebz]

I vote for pointing to the Kubernetes deprecation policy. It covers things like CLI flags and seems to be applicable to what we are doing.

[natasha41575]

I am also fine with pointing to the Kubernetes deprecation policy. If we are going to follow the kubernetes policy without any changes, do we need to have our own policy doc, or can we just have a link?

track the timeline in a centralized place (suggest under the root/README.md)

Are you thinking of adding a new section to the root/README.md, e.g. Deprecated features? Would it make sense to also have a page for deprecated features and their timelines on the docs website?

[yuwenma]

I'm thinking of a "discovery" table that contains all main kustomize features, showing the since-supported and til-unsupportedx versions, e.g. (the supported version field is very inaccurate)

Feature	supported version	status (rationale)	examples
base/overlay	v1.0.0+	stable	multibase
vars	v3.8(?) - v4.3	deprecating, See #2025

[KnVerey]

I like the idea of the table; it could be more convenient for users than combing through release notes, particularly in cases where a big version jump happens at once, e.g. in the Kustomize bundled with kubectl 1.20 vs. 1.21. (Sidenote: I think the issue about making kubectl kustomize version work properly is one of the most impactful unclaimed pieces of work we have open right now.)

A couple notes on differences/considerations for us vs. the standard deprecation policy:

1. Unlike kubectl, we can actually make major version bump releases. IMO this gives us more leeway with the deprecation cycle, as does being out of tree generally.

2. Despite the above, we should be careful to make sure major deprecations surface functionally in at least one kubectl kustomize release.

3. There are three different things we version independently in Kustomize, which may complicate the table somewhat:

• The CLI version. One CLI version can support multiple Kustomization versions. Flags are tied to this version exclusively. CLI is GA but has not to my knowledge followed the lengthy cycle in the official policy in the past.
• The Kustomization (and other resource) version. Most features are rooted in this version (and several that aren't, should be), and it is beta. AFAIK there's only been one version so far.
• The public APIs of our Go modules. Most if not all of these are alpha. Their version has no impact on consumers of prebuilt kustomize binaries.

Example implication: vars should always be supported by kustomize.config.k8s.io/v1beta1 Kustomization and should never be supported by kustomize.config.k8s.io/v1 Kustomization. CLI v4.X could support both Kustomization versions, and CLI v5 could drop kustomize.config.k8s.io/v1beta1 Kustomization. But if we do that and v5 exists ahead of the kubectl 1.23 release, we should bundle the latest v4.X kustomize instead because we're not emitting deprecation warnings in the version bundled with 1.22. That may mean maintaining a previous release branch more consciously for a period of time, or deliberately holding off the v5 release for quite a while after we're internally ready for it. We could also end up needing to do several major version bumps of the Go modules depending on when we graduate them vs. when various deprecations complete.

[natasha41575]

Would it make sense to have two tables, one for CLI, and one for the Kustomization? The CLI table can track status of supported commands and kustomization versions, while the Kustomization table can keep track of supported fields.

Regarding the public APIs of our Go modules - if we are going to have tables for these, I think they should go in their own directories, e.g. api/README.md.

[KnVerey]

Rather than a chart on our readme, we've decided to update the Kustomization field documentation with the support information

[yuwenma]

Rather than a chart on our readme, we've decided to update the Kustomization field documentation with the support information

Updated the description to track the work of "updating the Kustomization field documentation with the support information" and moved to project CLI V5

[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

[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:

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

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

/close

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue.

In response to this:

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:

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

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

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[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:

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

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

/close

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue.

In response to this:

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:

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

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

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[KnVerey]

/retitle Better document field/feature availability across Kustomize versions
/reopen

[k8s-ci-robot]

@KnVerey: Reopened this issue.

In response to this:

/retitle Better document field/feature availability across Kustomize versions
/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted