valkey: add argument_specs, move the provider check out of the task

[GeertJohan]

Split out of #707, which was too large to review in one go.

This is the same change for a single role, so the pattern can be judged on something small. Picked valkey because it's deployed by mini-lab.

What it does

• adds control-plane/roles/valkey/meta/argument_specs.yaml, documenting every variable the role takes (type, description, no_log on the secrets)
• moves valkey_backup_restore_sidecar_provider in ["local", "gcp", "s3"] int the spec as choices
• drops the second assert block, which re-checked valkey_backup_restore_sidecar_image_tag is defined - the first assert already covers that variable

Why the image variables stay in the assert

valkey_image_name/_tag and valkey_backup_restore_sidecar_image_name/_tag are resolved from the release vector by this role's own setup_yaml task.
Ansible inserts role argument validation before the first task of the role, so those variables are not defined yet at validation time and marking them required: true would fail every run. They are declared in the spec (for types and ansible-doc) but stay in the assert for the presence check. There is a comment in the spec saying so, so the next reader does not "fix" it.

Effect

A wrong ..._provider value now fails before any task runs instead of at the assert, and ansible-doc -t role can list the variables.

If this looks right, I will send the remaining roles the same way, a few per PR.

Used AI? ✨

Yes. Claude Fable 5

[Gerrit91]

/ok-to-build

[Gerrit91]

Finally found some time to look at it and I really like it!

The role already is a good example that the documentation is outdated. Do you think it would be possible to generate the role's README.md from ansible-doc -t role -r control-plane/roles valkey --json with a small python script helper?

I think it would work if:

• The role description would also be moved into the argument spec
• We come up with some generic doc snippets to be added in case the role depends on setup_yaml (with a link to how resolving the release vector works?) or when shared default variables are imported through role dependencies
• To enable everyone to update those docs, the generation could be invoked through a small container (similar to what I tried here: metal-stack/metal-ansible-modules#30)
• Did you consider adding the defaults to the argument spec? It seems pretty hard to keep them in-sync with the role defaults but would be really cool in a table.

[Gerrit91]

Must be a bool

[GeertJohan]

I like the idea of having README.md's generated from spec, would it make sense to have that be a separate PR to avoid scope creep?

[Gerrit91]

As we only take care of this specific role, I am fine to combine it with this PR. But we can also split it into two if it you want.

[vknabel]

Do we want to add options here and / or in other places?
Of course we don't have to mirror k8s here and especially not all levels deep, but it might make sense in some cases to at least provide top-level attributes. The resources aren't necessarily a good example of this. Might be handy for upcoming PRs though :)

e.g.

options:
  resources:
    type: dict
  limits:
    type: dict
  claims:
    type: list
    elements: dict

[Gerrit91]

For certain variables this would be quite useful. As long as it does not prevent some degree of freedom, which might already be used by some consumers.