Fix appearance and sync with latest changes

Change-Id: I06c931ece562137a1cd08d799ca70c946cd6848a
Blueprint: templates-for-networking

specs/7.0/networking-templates.rst

@@ -41,61 +41,65 @@ Proposed change
 ===============
 
 Template solution is proposed to provide the following capabilities:
+
 * Ability to create additional networks and delete networks (new API handlers
-to be added to support this).
+  to be added to support this).
 * Have a specific set of network roles.
 * Ability to create network only in case relevant node role is present on the
-node.
+  node.
 * Ability to provide custom networking topologies (e.g. subinterface bonding).
 
 Template solution details:
+
 * REST API handler is added to load/cancel template for given environment
-(/clusters/x/network_configuration/template/).
+  (/clusters/x/network_configuration/template/).
 * Template is applied during serialization if it was set for the env. So,
-template can be loaded/reloaded any time before deployment is started and after
+  template can be loaded/reloaded any time before deployment is started and
-reset. So, it is the same behaviour as for all network settings now. Deployment
+  after reset. So, it is the same behaviour as for all network settings now.
-serializer for networking will be selected with regard to the fact whether
+  Deployment serializer for networking will be selected with regard to the fact
-template was loaded or not.
+  whether template was loaded or not.
 * Template has priority over network schema (not network addresses or node
-groups) in the DB (explained better below). If it is applied then DB data
+  groups) in the DB (explained better below). If it is applied then DB data
-(related to network roles to networks mapping, networks to interfaces mapping
+  (related to network roles to networks mapping, networks to interfaces mapping
-and network objects topology) is ignored by networking serializer. If it is not
+  and network objects topology) is ignored by networking serializer. If it is
-applied then DB data is taken into account by networking serializer.
+  not applied then DB data is taken into account by networking serializer.
-Serialization of other data is not affected.
+  Serialization of other data is not affected.
 * Astute.yaml for particular node has priority over template by default.
-If yaml was uploaded for particular nodes serialized data for them will be
+  If yaml was uploaded for particular nodes serialized data for them will be
-taken from there. Additional flag is added to node to override network part of
+  taken from there. Additional flag is added to node to override network part
-astute.yaml. It the flag is set then network data is taken from serializer
+  of astute.yaml. It the flag is set then network data is taken from serializer
-output regardless of template presence. Node's yaml overriding task can be
+  output regardless of template presence. Node's yaml overriding task can be
-postponed due to lack of time.
+  postponed due to lack of time.
 * Template allows to override network roles to networks mapping and topology
-(to support complex cases which cannot be configured via API, like subinterface
+  (to support complex cases which cannot be configured via API, like
-bonding). Network roles' set can be not equal to core set, it is up to user.
+  subinterface bonding). Network roles' set can be not equal to core set, it is
-No verification of network roles' set is provided at this stage. Network roles
+  up to user. No verification of network roles' set is provided at this stage.
-to networks mapping can be set for each node role independently. Sets of
+  Network roles to networks mapping can be set for each node role
-network roles and networks may be different on every particular node.
+  independently. Sets of network roles and networks may be different on every
-Validation should be added to ensure that all required roles are present on
+  particular node. Validation should be added to ensure that all required roles
-every node. It's naturally done with network roles to tasks mapping but can be
+  are present on every node. It's naturally done with network roles to tasks
-postponed due to lack of time.
+  mapping but can be postponed due to lack of time.
 * Template allows to use distinct network schemes for different node roles and
-for different node network groups. It also allows to use different NICs' sets
+  for different node network groups. It also allows to use different NICs' sets
-for particular node network groups and particular nodes.
+  for particular node network groups and particular nodes.
 
 User should be able to use specific networks for swift & cinder traffic:
+
 * Puppet manifests should support separated network roles for these services.
 * Template solution will allow to use the separation of network roles and
-networks.
+  networks.
 
 All the networking metadata which is now defined within networks should be
 moved to network roles description:
+
 * Every task description has section [network_roles] where the list of names of
-network roles required is declared. (It's required for template validation at
+  network roles required is declared. (It's required for template validation at
-least.) It can be out of first feature release as not highest priority task
+  least.) It can be out of first feature release as not highest priority task
-which takes significant time.
+  which takes significant time.
 * Descriptions of network roles are propagated to Nailgun and include metadata
-which is required for serialization to orchestrator.
+  which is required for serialization to orchestrator.
 * VIPs assignment is done using network roles metadata instead of networks
-metadata. It is true for both template and general flow.
+  metadata. It is true for both template and general flow.
 
 
 Alternatives
@@ -110,19 +114,19 @@ Data model impact
 Template example::
 
     adv_net_template:
-      - node_group: default
+      default:
         nic_mapping:
           default:
             if1: eth0
             if2: eth1
-            if3: wlan0
+            if3: eth2
           node-3:
             if1: eth0
             if2: eth1
             if3: eth2
-            if4: eth3
+            if4: wlan0
         network_scheme:
-          common: &common
+          common:
             transformations:
               - action: add-br
                 name: br-fw-admin
@@ -137,7 +141,6 @@ Template example::
             roles:
               admin/pxe: br-fw-admin
               neutron/api: br-mgmt
-              neutron/mesh: br-mgmt
               mgmt/corosync: br-mgmt
               mgmt/database: br-mgmt
               mgmt/messaging: br-mgmt
@@ -158,7 +161,7 @@ Template example::
               swift/replication: br-storage
               ceph/replication: br-storage
               cinder/iscsi: br-storage
-          public: &public
+          public:
             transformations:
               - action: add-br
                 name: br-ex
@@ -179,7 +182,7 @@ Template example::
               ceph/radosgw: br-ex
               swift/public: br-ex
               neutron/floating: br-floating
-          private: &private
+          private:
             transformations:
               - action: add-br
                 name: br-prv
@@ -197,7 +200,6 @@ Template example::
               - br-aux
             roles:
               neutron/private: br-prv
-
         templates_for_node_role:
           controller:
             - common
@@ -207,29 +209,54 @@ Template example::
             - common
             - private
         network_assignments:
-          br-fw-admin:
+          storage:
-              subnet: fuelweb_admin
+            ep: br-storage
-          br-mgmt:
+          private:
-              subnet: management
+            ep: br-prv
-          br-ex:
+          public:
-              subnet: public
+            ep: br-ex
-          br-storage:
+          management:
-              subnet: storage
+            ep: br-mgmt
-          br-mesh:
+          fuelweb_admin:
-              subnet: private
+            ep: br-fw-admin
-          br-prv:
-              subnet: private
 
 Network roles are introduced. Network role description contain:
+
 * id - string, can be treated as name. It should be used in tasks' descriptions
-for referencing network roles required for particular task. It is also used in
+  for referencing network roles required for particular task. It is also used
-manifests.
+  in manifests.
-* network properties - dictionary, properties which are required for underlying
+* default_mapping - string, name of the network to map this role be default
-network are described here, like CIDR, gateway, VIPs.
+  (when template is not in use).
+* properties - dictionary, properties which are required for underlying network
+  are described here, like CIDR, gateway, VIPs.
 * metadata - dictionary, it is metadata which is not related to networks,
-e.g. neutron settings. It is in our DSL format. It will be shown in UI and
+  e.g. neutron settings. It is in our DSL format. It will be shown in UI and
-could be edited there. It is passed to orchestrator as is. Nailgun doesn't
+  could be edited there. It is passed to orchestrator as is. Nailgun doesn't
-process it.
+  process it. It will not be used in 7.0. So, it can be skipped for now.
+
+Network role description example::
+
+    id: "mgmt/vip"
+    default_mapping: "management"
+    properties:
+      subnet: true
+      gateway: false
+      vip:
+        - name: "vrouter"
+          namespace: "vrouter"
+        - name: "management"
+          namespace: "haproxy"
+          node_roles: ["primary-controller", "controller"]
+
+VIPs can be requested in network role's description. Description of VIP
+includes:
+
+* name - string, it should be unique name within the environment, it cannot be
+  skipped.
+* namespace - string, network namespace, that should be used for landing of
+  the VIP, will be serialized to null when skipped.
+* node_roles - list, node roles where VIPs should be set up. It can be skipped.
+  Its value will be set to ["primary-controller", "controller"] then.
 
 Network role descriptions are accessible for Nailgun. They are accumulated into
 network_role_metadata field of Release DB table. They are used for assignment
@@ -304,11 +331,12 @@ into DB. If validation failed DB is kept without changes.
 Template is cancelled if empty template body was provided with this API call.
 DB will be updated with empty template then.
 
-Add "/clusters/x/network_configuration/networks/" URL to create/remove networks
+Add "/networks/" URL to create networks and get their parameters (POST/GET).
-for given environment.
+Add "/networks/x/" URL to get/set parameters of individual network and delete
+network (GET/PUT/DELETE).
 
-This handler will support POST/DELETE operations to create/remove networks.
+All parameters and metadata can be changed for individual network via
-Networks' configuration should be set using existing API.
+"/networks/x/".
 
 
 Upgrade impact
@@ -443,8 +471,6 @@ Acceptance Criteria
 
 * Descriptions of network roles are propagated to Nailgun and include metadata
   which is required for serialization to orchestrator.
-* Every task description has section [network_roles] where the list of names of
-  network roles required is declared.
 * API handler is added to load/cancel template for given environment.
 * API handler is added to create/remove networks for given environment.
 * Template is applied during serialization if it was set for the env.