Changing Kubernetes version documentation incomplete.

[ScionOfDesign]

The kind documentation uses the following as an example of changing the Kubernetes version:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes: 
- role: control-plane 
- role: worker
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55

However, this configuration can lead to kind using a different version of Kubernetes for the control-plane. This causes an error when attempting to join the worker nodes. The following configuration works instead:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes: 
- role: control-plane
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55
- role: worker
  image: kindest/node:v1.16.4@sha256:b91a2c2317a000f3a783489dfb755064177dbc3a0b2f4147d50f04825d016f55

[BenTheElder]

That's mostly due to this particular version being old vs the default in the current kind release, you do not strictly have to use the exact same version on all nodes, though this is poorly tested. You should be able to set a single node, as discussed in the docs I believe you're referencing at https://kind.sigs.k8s.io/docs/user/configuration/#kubernetes-version

Officially kubernetes supports version skew, and kind does it's best. https://kubernetes.io/releases/version-skew-policy/

The primary docs for changing version when creating a cluster are here in the initial user guide / quick start: https://kind.sigs.k8s.io/docs/user/quick-start/#creating-a-cluster

If you want to change all nodes, it's easier to use the --image flag which applies to all nodes in config

We could perhaps put a bogus dummy image value there instead, to make it clearer that we don't intend to literally use that config, we're just illustrating the fields.

[ScionOfDesign]

Yeah, some additional explanation about that would be ideal. The #kubernetes-version header pops out the most when searching for information on how to change the version.

[BenTheElder]

Marking this issue for help. /help

https://kind.sigs.k8s.io/docs/contributing/getting-started/ covers how to contribute to the docs.

We should probably:

• add a note about the Kubernetes skew policy applying
• cross link to the main quick start docs about how to use node images
• perhaps consider rewriting this sample config to have a bogus image value so it isn't copy pasted with an image that isn't necessarily for the current kind release

[k8s-ci-robot]

@BenTheElder: This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-help command.

In response to this:

Marking this issue for help. /help

https://kind.sigs.k8s.io/docs/contributing/getting-started/ covers how to contribute to the docs.

We should probably:

• add a note about the Kubernetes skew policy applying
• cross link to the main quick start docs about how to use node images
• perhaps consider rewriting this sample config to have a bogus image value so it isn't copy pasted with an image that isn't necessarily for the current kind release

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.

[VibhorChinda]

I want to help here :))

Do we just need to change the documentation ??

[BenTheElder]

Yes, thank you, we need to write some more content covering https://github.com/kubernetes-sigs/kind/issues/2792#issuecomment-1164866110

At some point I think we're also going to need to break up the docs more, but for now probably just additional details under "Creating a cluster" in the quick-start.

Our contributing guide covers how documentation works under the development page https://kind.sigs.k8s.io/docs/contributing/getting-started/

[VibhorChinda]

Understood :)) Can someone assign this to me. Thanks

[BenTheElder]

/assign @VibhorChinda