search

kubernetes-sigs / kustomize

Customization of kubernetes YAML configurations
Apache License 2.0
11.09k stars 2.26k forks source link

Better document field/feature availability across Kustomize versions #4121

Open yuwenma opened 3 years ago

yuwenma commented 3 years ago

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 commented 3 years ago

@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](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
yuwenma commented 3 years ago

@monopole @KnVerey @natasha41575 Thoughts?

mikebz commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

yuwenma commented 3 years ago

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 commented 2 years ago

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:

You can:

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

/lifecycle stale

k8s-triage-robot commented 2 years ago

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:

You can:

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

/lifecycle rotten

k8s-triage-robot commented 2 years ago

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:

You can:

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

/close

k8s-ci-robot commented 2 years ago

@k8s-triage-robot: Closing this issue.

In response to [this](https://github.com/kubernetes-sigs/kustomize/issues/4121#issuecomment-1159537286): >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][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
k8s-triage-robot commented 2 years ago

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:

You can:

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

/close

k8s-ci-robot commented 2 years ago

@k8s-triage-robot: Closing this issue.

In response to [this](https://github.com/kubernetes-sigs/kustomize/issues/4121#issuecomment-1228939615): >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][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
KnVerey commented 1 year ago

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

k8s-ci-robot commented 1 year ago

@KnVerey: Reopened this issue.

In response to [this](https://github.com/kubernetes-sigs/kustomize/issues/4121#issuecomment-1341655720): >/retitle Better document field/feature availability across Kustomize versions >/reopen Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
k8s-triage-robot commented 10 months ago

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

You can:

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

/remove-triage accepted