[ovs-dev] [PATCH] ovn-controller: Document southbound database use and graceful termination.

[Han Zhou]

On Fri, Feb 2, 2018 at 9:44 AM, Ben Pfaff <blp at ovn.org> wrote:
>
> A lot of people seem to think that "kill" gracefully terminates
> ovn-controller, but it doesn't, so this documentation at least provides
> something to point to.
>
> Signed-off-by: Ben Pfaff <blp at ovn.org>
> ---
>  ovn/controller/ovn-controller.8.xml | 47
+++++++++++++++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)
>
> diff --git a/ovn/controller/ovn-controller.8.xml
b/ovn/controller/ovn-controller.8.xml
> index 0df59acd3c8b..96a58ddf358d 100644
> --- a/ovn/controller/ovn-controller.8.xml
> +++ b/ovn/controller/ovn-controller.8.xml
> @@ -304,6 +304,53 @@
>        </dd>
>      </dl>
>
> +    <h1>OVN Southbound Database Usage</h1>
> +
> +    <p>
> +      <code>ovn-controller</code> reads from much of the
> +      <code>OVN_Southbound</code> database to guide its operation.
> +      <code>ovn-controller</code> also writes to the following tables:
> +    </p>
> +
> +    <dl>
> +      <dt><code>Chassis</code></dt>
> +      <dd>
> +        Upon startup, <code>ovn-controller</code> creates a row in this
table
> +        to represent its own chassis.  Upon graceful termination, e.g.
with
> +        <code>ovs-appctl -t ovn-controller exit</code> (but not
> +        <code>SIGTERM</code>), <code>ovn-controller</code> removes its
row.
> +      </dd>
> +
> +      <dt><code>Encap</code></dt>
> +      <dd>
> +        Upon startup, <code>ovn-controller</code> creates a row or rows
in this
> +        table that represent the tunnel encapsulations by which its
chassis can
> +        be reached, and points its <code>Chassis</code> row to them.
Upon
> +        graceful termination, <code>ovn-controller</code> removes these
rows.
> +      </dd>
> +
> +      <dt><code>Port_Binding</code></dt>
> +      <dd>
> +        At runtime, <code>ovn-controller</code> sets the
<code>chassis</code>
> +        columns of ports that are resident on its chassis to point to its
> +        <code>Chassis</code> row, and, conversely, clears the
> +        <code>chassis</code> column of ports that point to its
> +        <code>Chassis</code> row but are no longer resident on its
chassis.
> +        The <code>chassis</code> column has a weak reference type, so
when
> +        <code>ovn-controller</code> gracefully exits and removes its
> +        <code>Chassis</code> row, the database server automatically
clears any
> +        remaining references to that row.
> +      </dd>
> +
> +      <dt><code>MAC_Binding</code></dt>
> +      <dd>
> +        At runtime, <code>ovn-controller</code> updates the
> +        <code>MAC_Binding</code> table as instructed by
<code>put_arp</code>
> +        and <code>put_nd</code> logical actions.  These changes persist
beyond
> +        the lifetime of <code>ovn-controller</code>.
> +      </dd>
> +    </dl>
> +
>      <h1>Runtime Management Commands</h1>
>      <p>
>        <code>ovs-appctl</code> can send commands to a running
> --
> 2.15.1
>

Thanks Ben!

Acked-by: Han Zhou <zhouhan at gmail.com>