docs: add charm-user in the charmcraft.yaml file reference (#2195)

The `charm-user` field is documented in the metadata.yaml file
reference, but is missing from the charmcraft.yaml file reference, even
though it does work there. This PR adds it to that reference.

As the docs currently are, it gives the incorrect impression that you
cannot use the combined charmcraft.yaml file to specify `charm-user`,
and must have separate metadata, actions, and config files.

---------

Co-authored-by: Erin Conley <[email protected]>
Co-authored-by: Ali UĞUR <[email protected]>

Author: 3 people

docs/reference/files/charmcraft-sample-charm.yaml

@@ -43,6 +43,7 @@ charm-libs:
     version: "1"
   - lib: mysql.mysql
     version: "0.5"
+charm-user: sudoer
 config:
   options:
     name:

docs/reference/files/charmcraft-yaml-file.rst

@@ -346,6 +346,42 @@ and the lib version (in ``"<api version>[.<patch version>]"`` string format).
 
 .. literalinclude:: charmcraft-sample-charm.yaml
     :start-at: charm-libs:
+    :end-before: charm-user:
+
+
+.. _charmcraft-yaml-key-charm-user:
+
+``charm-user``
+--------------
+
+.. important::
+
+    ``charm-user`` was added in Juju 3.6.0. It's currently only supported by
+    Kubernetes charms and has no effect on machine charms.
+
+**Status:** Optional. Recommended for Kubernetes charms.
+
+**Purpose:** The ``charm-user`` key  allows charm authors to specify that their charm
+hook code does not need to be run as root. This key, in combination with ``uid`` + ``gid``
+fields in ``containers``, allows the charm to be run rootless. If set to ``root``,
+the charm runs as root. If set to ``sudoer`` or ``non-root``, the charm runs as a user
+other than root. If the value is ``sudoer``, the charm will be run as a user
+with access to sudo to elevate its privileges.
+
+**Structure:** The key consists of a single value. One of ``root``, ``sudoer`` or
+``non-root``.
+
+.. code-block:: yaml
+
+    # (Optional) What kind of user is required to run the charm code.
+    # It can be one of root, sudoer or non-root.
+    # Added in Juju 3.6.0. If not specified, root is assumed.
+    charm-user: <one of root, sudoer or non-root>
+
+**Example:**
+
+.. literalinclude:: charmcraft-sample-charm.yaml
+    :start-at: charm-user:
     :end-before: config:
 
 

docs/reference/files/metadata-yaml-file.rst

@@ -431,17 +431,17 @@ Examples:
 
 .. important::
 
-    ``charm-user`` was added in Juju 3.6.0. Currently is only supported on Kubernetes
-    charms and has no effect on machine charms.
+    ``charm-user`` was added in Juju 3.6.0. It's currently only supported by
+    Kubernetes charms and has no effect on machine charms.
 
 **Status:** Optional. Recommended for Kubernetes charms.
 
 **Purpose:** The ``charm-user`` key  allows charm authors to specify that their charm
-hook code does not need to be run as root. This key, in addition to ``uid`` + ``uid``
-fields in ``containers``, allows charms to be run rootless. The value of ``root``
-ensures the charm runs as root. Both ``sudoer`` and ``non-root`` will run as a user
-other than root. In the case of the value ``sudoer``, the charm will be run as a user
-with access to sudo to elevate it's privileges.
+hook code does not need to be run as root. This key, in combination with ``uid`` + ``gid``
+fields in ``containers``, allows the charm to be run rootless. If set to ``root``,
+the charm runs as root. If set to ``sudoer`` or ``non-root``, the charm runs as a user
+other than root. If the value is ``sudoer``, the charm will be run as a user
+with access to sudo to elevate its privileges.
 
 **Structure:** The key consists of a single value. One of ``root``, ``sudoer`` or
 ``non-root``.

tests/spread/smoketests/basic/charmcraft-platforms-24.04-all.yaml

@@ -12,3 +12,5 @@ parts:
   my-charm:
     plugin: charm
     source: .
+charm-user: sudoer
+