[docs]: Users and Groups module schema examples code blocks differ from explanation text

[neitsab]

Documentation request

https://docs.cloud-init.io/en/latest/reference/modules.html#mod-cc-users-groups "Examples" tab : the sentence

Password-based login is rejected, but the GitHub user TheRealFalcon and the Launchpad user falcojr can SSH as newsuper.

has made its way to examples 3 and 4 explanations, but is not reflected in the given examples (emphasis mine):

Example 3: Skip creation of the default user and only create newsuper. Password-based login is rejected, but the GitHub user TheRealFalcon and the Launchpad user falcojr can SSH as newsuper. The default shell for newsuper is bash instead of system default.

#cloud-config
users:
- name: newsuper
  shell: /bin/bash

Example 4: Skip creation of the default user and only create newsuper. Password-based login is rejected, but the GitHub user TheRealFalcon and the Launchpad user falcojr can SSH as newsuper. doas/opendoas is configured to permit this user to run commands as other users (without being prompted for a password) except not as root.

#cloud-config
users:
- doas: [permit nopass newsuper, deny newsuper as root]
  name: newsuper

Source:

• https://github.com/canonical/cloud-init/blob/207d38fa067a1dd265ab076bbc2f32e3b8bbe899/doc/module-docs/cc_users_groups/data.yaml#L73C21-L75C20
• https://github.com/canonical/cloud-init/blob/207d38fa067a1dd265ab076bbc2f32e3b8bbe899/doc/module-docs/cc_users_groups/data.yaml#L80C21-L82C20

Required matching code (from https://github.com/canonical/cloud-init/blob/207d38fa067a1dd265ab076bbc2f32e3b8bbe899/doc/rtd/reference/yaml_examples/user_groups.rst#add-users-to-the-system)

  ssh_import_id:
    - lp:falcojr
    - gh:TheRealFalcon

So either we remove the sentence or add the matching code, as you see fit.

Thanks

[neitsab]

I just realized example 7 has the opposite issue:

Example 7: Override any default_user config in /etc/cloud/cloud.cfg with supplemental config options. This config will make the default user mynewdefault and change the user to not have sudo rights.

#cloud-config
ssh_import_id: [chad.smith]
user: {name: mynewdefault, sudo: null}

Here we have the ssh_import_id: [chad.smith] code example without the correct explanation.

[blackboxsw]

Thanks for the detailed report. This is actionable as filed: you’ve identified the affected docs page, linked the source locations, and pointed out both the explanation/code mismatch in examples 3 and 4 and the inverse mismatch in example 7.

We will help anyone review and merge these doc changes willing to propose an upstream PR.

3 & 4. For clarify, I think the changeset for 3 should be within the newsuper users list element and not a top-level ssh_import_id key.

  ssh_import_id: [ TheRealFalcon, lp:falcojr ]

7. This documented example needs only a fix in rtd/module-docs/cc_users_groups/data.yaml for example 7 adding the suffix '.... sudo rights, and allowing the Launchad user chad.smith to SSH as mynewdefault.'

[neitsab]

Thanks for the pointers, I wanted to get your feedback on how one should go about fixing 3 & 4 (remove the sentence or add the code example).

To clarify: should the sentence be kept in both (and so the code example be added as well) or just in one of the two (and therefore, the sentence removed from the description of the other) ? From what you wrote ("I think the changeset for 3 should be within") I get that the code example should be added in example 3, but what about example 4 ?

I'm preparing a PR.

[neitsab]

For now I've settled on adding the code example to 3 and removing the sentence from 4. Let me know what you think.