Ansible variables: reorganize defaults, documentation and inventory samples

[VannTen]

What would you like to be added:

• [ ] split up kubespray-defaults into defaults/main.yml in the role where the variable is used (when the variable is used by multiple role, have a separate _defaults role as a role dependency in every user, where is the most logical user / (dns_mode -> coredns for instance)

  • adapt the tooling (checksum scripts updater, etc)

• [ ] eliminate all instances of default filter in roles => var should have a default defined only once

• [ ] eliminates docs/vars.md and either use the default files directly as documentation (enforcing proper comment) or generates docs from them => the point being one single source of truth

• [ ] eliminate inventory samples covering all possible variables combination (see #10645 , this causes confusions for users) and replace them with minimal samples changing only what's needed. This also hides "missing default value in roles" bugs.

• [ ] establish a clear distinction between defaults (=> user customisable) and vars (=> internal use)

Why is this needed:

• self contained roles
• avoiding drift between the documentation and the code
• one source of truth for defaults
• might be better perf (avoid needlessly loading vars) but I don't think it would be noticeable
• clean up playbooks structure with all the kubespray-defaults invocations

(I've started #10626 which is part of that)

Opinions ? @floryut @yankay @MrFreezeex

[MrFreezeex]

split up kubespray-defaults into defaults/main.yml in the role where the variable is used (when the variable is used by multiple role, have a separate _defaults role as a role dependency in every user, where is the most logical user / (dns_mode -> coredns for instance)

I have mixed feeling about that. For variable that can be self contained in their own roles, sure I think that's a good idea to remove those from kubespray-default and include it directly in their own roles. For other variables not sure, IMO we should cleanup kubespray-default first and then decide depending on the resulting file if it's worth it.

eliminate all instances of default filter in roles => var should have a default defined only once

:100:

eliminates docs/vars.md and either use the default files directly as documentation (enforcing proper comment) or generates docs from them => the point being one single source of truth

:+1:

eliminate inventory samples covering all possible variables combination (see https://github.com/kubernetes-sigs/kubespray/issues/10645 , this causes confusions for users) and replace them with minimal samples changing only what's needed.

So yes indeed the current upgrade workflow is not the best, however I and possibly many other use the sample as documentation purposes. I guess an additional minimal template with only popular choices/recommended default could help here but removing the sample should depends on what we do on the previous point about doc as well...

[VannTen]

For other variables not sure, IMO we should cleanup kubespray-default first and then decide depending on the resulting file if it's worth it.

Good point. This is not gonna fit in one PR anyway, so I agree, we should do the obvious first and only then see what's left.

... however I and possibly many other use the sample as documentation purposes.

I think the problem mentionned in the linked issue is that the sample is used both as a template for new inventory (which IMO it should not) and as documentation (which is fine). If our defaults files are organized correctly, generating an equivalent to that should not be hard (find -name 'defaults/**/*.yml' -exec cat {} + > all_vars, something like that).

The issue with the "sample as template" is that user copy the sample as their inventory and once they upgrade kubespray, the sample is no longer reflecting reality. (new vars are fine, but what about changed defaults ? => argument could be made about incompatible defaults change).

[VannTen]

Another thing (I'll add to OP): I think we should have a more clear separation between defaults (= user can customize) and vars (= internal use) and use defaults for the former and vars for the latter. We have some variables which I don't think anyone should modify, and codifying that expectation would be IMO helpful.

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[VannTen]

/remove-lifecycle stale /lifecycle active

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[VannTen]

/lifecycle frozen /remove-lifecycle stale

[ant31]

It should be possible to run kubespray without any variable defined in in inventory/group_vars (all defaults are enough) and with tags (e.g run only 'etcd'). I'm not sure if it's still tested in the CI, if not we should add back the test.

From what I remember kubespray-default was introduced to be able to do that. There are many variable that are across many roles (think bin_dir).

Yes to generate doc from defaults.