Flesh out netowrk config list

Add support for indicating default_interface. Also, add some validation
and normalization code, some interface methods and, shockingly,
documentation.

Change-Id: Ib45b68894585ac02821d5d2376510fd7a8e8ee40

2 files changed, 48 insertions, 0 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index bf667b7..f7263c9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,6 +6,7 @@
    vendor-support
    contributing
    installation
+   network-config
    api-reference
    releasenotes
 
diff --git a/doc/source/network-config.rst b/doc/source/network-config.rst
new file mode 100644
index 0000000..9bbbf9d
--- /dev/null
+++ b/doc/source/network-config.rst
@@ -0,0 +1,47 @@
+==============
+Network Config
+==============
+
+There are several different qualities that networks in OpenStack might have
+that might not be able to be automatically inferred from the available
+metadata. To help users navigate more complex setups, `os-client-config`
+allows configuring a list of network metadata.
+
+.. code-block:: yaml
+
+  clouds:
+    amazing:
+      networks:
+      - name: blue
+        routes_externally: true
+      - name: purple
+        routes_externally: true
+        default_interface: true
+      - name: green
+        routes_externally: false
+      - name: purple
+        routes_externally: false
+        nat_destination: true
+
+Every entry must have a name field, which can hold either the name or the id
+of the network.
+
+`routes_externally` is a boolean field that labels the network as handling
+north/south traffic off of the cloud. In a public cloud this might be thought
+of as the "public" network, but in private clouds it's possible it might
+be an RFC1918 address. In either case, it's provides IPs to servers that
+things not on the cloud can use. This value defaults to `false`, which
+indicates only servers on the same network can talk to it.
+
+`default_interface` is a boolean field that indicates that the network is the
+one that programs should use. It defaults to false. An example of needing to
+use this value is a cloud with two private networks, and where a user is
+running ansible in one of the servers to talk to other servers on the private
+network. Because both networks are private, there would otherwise be no way
+to determine which one should be used for the traffic.
+
+`nat_destination` is a boolean field that indicates which network floating
+ips should be attached to. It defaults to false. Normally this can be inferred
+by looking for a network that has subnets that have a gateway_ip. But it's
+possible to have more than one network that satisfies that condition, so the
+user might want to tell programs which one to pick.