[PATCH 3/7] docs: added rng schema and formatdomain for NFS

[Peter Krempa]

On Tue, Dec 29, 2020 at 15:21:25 -0600, Ryan Gahagan wrote:
> Signed-off-by: Ryan Gahagan <rgahagan at cs.utexas.edu>
> ---
>  docs/formatdomain.rst         | 11 +++++++++-
>  docs/schemas/domaincommon.rng | 38 +++++++++++++++++++++++++++++++++++
>  2 files changed, 48 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 512939679b..23a7bca643 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -2370,6 +2370,14 @@ paravirtualized driver is specified via the ``disk`` element.
>         </source>
>         <target dev='sdb' bus='scsi'/>
>       </disk>
> +     <disk type='network' device='disk'>
> +       <driver name='qemu' type='raw'/>
> +       <source protocol='nfs' name='PATH'>
> +         <host name='example.com' port='2049'/>
> +         <nfs user='USER' group='GROUP'/>
> +       </source>
> +       <target dev='vda' bus='virtio'/>
> +     </disk>
>       <disk type='network' device='lun'>
>         <driver name='qemu' type='raw'/>
>         <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
> @@ -2491,7 +2499,7 @@ paravirtualized driver is specified via the ``disk`` element.
>     ``network``
>        The ``protocol`` attribute specifies the protocol to access to the
>        requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog",
> -      "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp".
> +      "gluster", "vxhs", "nfs", "http", "https", "ftp", ftps", or "tftp".

The docs is missing any description of the user/group fields. Please
include the syntax as well.

Additionally we tend to include any caveats of the initial
implementation. In this case you should include that NFS-backed disks
work only with TCP and port must be omitted.

>  
>        For any ``protocol`` other than ``nbd`` an additional attribute ``name``
>        is mandatory to specify which volume/image will be used.
> @@ -2601,6 +2609,7 @@ paravirtualized driver is specified via the ``disk`` element.
>        sheepdog one of the sheepdog servers (default is localhost:7000) zero or one                                                  7000
>        gluster  a server running glusterd daemon                        one or more ( :since:`Since 2.1.0` ), just one prior to that 24007
>        vxhs     a server running Veritas HyperScale daemon              only one                                                     9999
> +      nfs      a server running Network File System                    only one ( :since:`Since 7.0.0` )                            2049

You've dropped the code which sets the default port so this isn't
accurate.


>        ======== ======================================================= ============================================================ ================
>  
>        gluster supports "tcp", "rdma", "unix" as valid values for the transport
> diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
> index 17e25f14f2..4ddbf13ec4 100644
> --- a/docs/schemas/domaincommon.rng
> +++ b/docs/schemas/domaincommon.rng
> @@ -1774,6 +1774,27 @@
>      </element>
>    </define>
>  
> +  <define name="diskSourceNetworkNFS">
> +    <element name="nfs">

This will need changes after Daniel's suggestion.

> +      <optional>
> +        <attribute name="user">
> +          <choice>
> +            <ref name="unsignedInt"/>

Note that 'unsignedInt' doesn't actually allow the '+' prefix.

> +            <ref name="genericName"/>

But both numbers and strings started with + are covered by genericName,
so the choice isn't required.

> +          </choice>
> +        </attribute>
> +      </optional>
> +      <optional>
> +        <attribute name="group">
> +          <choice>
> +            <ref name="unsignedInt"/>
> +            <ref name="genericName"/>

Same here.

> +          </choice>
> +        </attribute>
> +      </optional>
> +    </element>
> +  </define>
> +
>    <define name="diskSourceNetworkProtocolRBD">
>      <element name="source">
>        <interleave>
> @@ -2039,6 +2060,22 @@
>      </element>
>    </define>
>  
> +  <define name="diskSourceNetworkProtocolNFS">
> +    <element name="source">
> +      <interleave>
> +        <attribute name="protocol">
> +          <choice>
> +            <value>nfs</value>
> +          </choice>
> +        </attribute>
> +        <attribute name="name"/>
> +        <ref name="diskSourceCommon"/>
> +        <ref name="diskSourceNetworkHost"/>

This allows also 'port' and non TCP transports. It's okay to simplify
the schema though and use the generic type. The code will need to reject
those when we'll validate whether the disk is possible to represent for
qemu.