Add --description flag to create type CLI commands

[luissimas]

Required information

• Distribution: Ubuntu
• Distribution version: 22.04 (Jammy)

Issue description

The Incus client CLI does not expose a way to specify the storage pool description upon its creation via the storage create subcommand. This is possible when creating networks, but only when specifying a yaml file via stdin.

This is not a functional issue per se, but I think it's a gap in the CLI user experience. I think Incus could provide a optional --description flag specific to the storage create and network create subcommands to allow users to set the description of those entities upon their creation.

The final user experience could look something like the following:

$ incus storage create my-pool dir source=/data/incus --description "My local storage pool"
$ incus network create my-network --type bridge --description "My local bridge network"

Additionally, the storage create command should be able to get the description from the stdin yaml file, not only the config parameter for the storage pool. This will make its behavior consistent with network create.

Steps to reproduce

1. Install the incus package from the Zabbly stable repository
2. Bootstrap the Incus server
3. Try to create a storage pool with a description

We cannot set the description of a storage pool in its creation:

# mkdir data1 data2
# incus storage ls
+---------+--------+----------------------+---------+---------+
|  NAME   | DRIVER |     DESCRIPTION      | USED BY |  STATE  |
+---------+--------+----------------------+---------+---------+
| default | btrfs  | Default storage pool | 1       | CREATED |
+---------+--------+----------------------+---------+---------+
# incus storage create pool1 dir source=/root/data1 --description "Sample description"
Error: unknown flag: --description
# incus storage create pool1 dir source=/root/data1
Storage pool pool1 created
# incus storage ls
+---------+--------+----------------------+---------+---------+
|  NAME   | DRIVER |     DESCRIPTION      | USED BY |  STATE  |
+---------+--------+----------------------+---------+---------+
| default | btrfs  | Default storage pool | 1       | CREATED |
+---------+--------+----------------------+---------+---------+
| pool1   | dir    |                      | 0       | CREATED |
+---------+--------+----------------------+---------+---------+
# cat pool.yaml
description: Test description
config:
  source: /root/data2
# incus storage create pool2 dir < ./pool.yaml
Storage pool pool2 created
# incus storage ls
+---------+--------+----------------------+---------+---------+
|  NAME   | DRIVER |     DESCRIPTION      | USED BY |  STATE  |
+---------+--------+----------------------+---------+---------+
| default | btrfs  | Default storage pool | 1       | CREATED |
+---------+--------+----------------------+---------+---------+
| pool1   | dir    |                      | 0       | CREATED |
+---------+--------+----------------------+---------+---------+
| pool2   | dir    |                      | 0       | CREATED |
+---------+--------+----------------------+---------+---------+
# incus storage show pool2
config:
  source: /root/data2
description: ""
name: pool2
driver: dir
used_by: []
status: Created
locations:
- none

Note that we can achieve the desired outcome with networks by using a yaml file:

# ls
net.yaml  snap
# incus network ls
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
|   NAME   |   TYPE   | MANAGED |      IPV4      |           IPV6            |   DESCRIPTION   | USED BY |  STATE  |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| enp5s0   | physical | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| incusbr0 | bridge   | YES     | 10.103.82.1/24 | fd42:5e7f:788c:6cea::1/64 | Default network | 1       | CREATED |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| lo       | loopback | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| lxdbr0   | bridge   | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
# incus network create net1 --type bridge --description "Test description"
Error: unknown flag: --description
# incus network create net1 --type bridge
Network net1 created
# incus network ls
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
|   NAME   |   TYPE   | MANAGED |      IPV4      |           IPV6            |   DESCRIPTION   | USED BY |  STATE  |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| enp5s0   | physical | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| incusbr0 | bridge   | YES     | 10.103.82.1/24 | fd42:5e7f:788c:6cea::1/64 | Default network | 1       | CREATED |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| lo       | loopback | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| lxdbr0   | bridge   | NO      |                |                           |                 | 0       |         |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
| net1     | bridge   | YES     | 10.47.204.1/24 | fd42:954b:77bf:944f::1/64 |                 | 0       | CREATED |
+----------+----------+---------+----------------+---------------------------+-----------------+---------+---------+
# cat net.yaml
description: Test description
# incus network create net2 --type bridge < ./net.yaml
Network net2 created
# incus network ls
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
|   NAME   |   TYPE   | MANAGED |      IPV4       |           IPV6            |   DESCRIPTION    | USED BY |  STATE  |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| enp5s0   | physical | NO      |                 |                           |                  | 0       |         |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| incusbr0 | bridge   | YES     | 10.103.82.1/24  | fd42:5e7f:788c:6cea::1/64 | Default network  | 1       | CREATED |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| lo       | loopback | NO      |                 |                           |                  | 0       |         |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| lxdbr0   | bridge   | NO      |                 |                           |                  | 0       |         |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| net1     | bridge   | YES     | 10.47.204.1/24  | fd42:954b:77bf:944f::1/64 |                  | 0       | CREATED |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+
| net2     | bridge   | YES     | 10.202.137.1/24 | fd42:f769:1020:eb5::1/64  | Test description | 0       | CREATED |
+----------+----------+---------+-----------------+---------------------------+------------------+---------+---------+

[luissimas]

@stgraber if the proposed behavior makes sense and is something that you'd want included in Incus, I'd like to work on implementing it. From what I've seen we'll need to change only the CLI command definitions, as the API schema already supports the description field in the POST/PUT requests for both storage pools and networks.

Additionally, it seems that the behavior for network creation is to give priority to command-line properties over the ones provided via stdin in the case of conflict. I think it makes sense to replicate that behavior to the storage pool creation for the sake of consistency, but let me know what you think.

[stgraber]

@luissimas yeah, I think adding --description to the various commands would make sense.
That will save you a call to set --property object description=FOO

[stgraber]

Here is what I think is the full list of commands that should support --description:

• config trust add-certificate
• cluster group create
• create
• image alias create
• launch
• network create
• network acl create
• network acl rule add
• network forward create
• network forward port add
• network load-balancer create
• network load-balancer backend add
• network load-balancer port add
• network peer create
• network zone create
• network zone record add
• profile create
• project create
• snapshot create
• storage create
• storage bucket create
• storage bucket key create
• storage volume create
• storage volume snapshot create