Update documentation comments in site manfiests

Change-Id: If384d7a12d01054caea73c5bf1d4c4f0d19909bd
Signed-off-by: Kaspars Skels <kaspars.skels@att.com>

2 files changed, 85 insertions, 114 deletions

diff --git a/site/intel-pod17/networks/common-addresses.yaml b/site/intel-pod17/networks/common-addresses.yaml
index e3dfad9..758ba9b 100644
--- a/site/intel-pod17/networks/common-addresses.yaml
+++ b/site/intel-pod17/networks/common-addresses.yaml
@@ -1,6 +1,6 @@
 ---
 # The purpose of this file is to define network related paramters that are
-# referenced elsewhere in the manifests for this site.
+# referenced (substituted) elsewhere in the manifests for this site.
 #
 schema: pegleg/CommonAddresses/v1
 metadata:
@@ -12,20 +12,29 @@ metadata:
   storagePolicy: cleartext
 data:
   calico:
-    # NEWSITE-CHANGEME: The interface that calico will use. Update if your
-    # logical bond interface name or calico VLAN have changed from the reference
+    # NEWSITE-CHANGEME: The interface that Calico will use. Update if your
+    # logical interface name or Calico VLAN have changed from the reference
     # site design.
-    # This should be whichever
-    # bond and VLAN number specified in networks/physical/networks.yaml for the Calico
-    # network. E.g. VLAN 22 for the calico network as a member of bond0, you
-    # would set "interface=bond0.22" as shown here.
+    # This should be whichever interface (or bond) and VLAN number specified in
+    # networks/physical/networks.yaml for the Calico network.
+    # E.g. you would set "interface=ens785f0" as shown here.
     ip_autodetection_method: interface=ens785f0
     etcd:
-      # etcd service IP address
+      # The etcd service IP address.
+      # This address must be within data.kubernetes.service_cidr range
       service_ip: 10.96.232.136
 
+  # NEWSITE-CHANGEME: Update virtual IPs to be used for deployment.
+  # These IPs are imporant and tied to FQDN/DNS registration for the site, see more at
+  # https://airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html#register-dns-names
   vip:
+    # Used for accessing Airship/OpenStack APIs (ingress of kube-system)
+    # The address is selected from DMZ network specified in
+    # networks/physical/networks.yaml
     ingress_vip: '10.10.170.100/32'
+    # Used for bare-metal deployment (PXE boot, fetching Drydock bootactions)
+    # The address is selected from Admin network specified in
+    # networks/physical/networks.yaml
     maas_vip: '10.10.171.100/32'
 
   dns:
@@ -51,15 +60,16 @@ data:
     # the Genesis role. Refer to the hostname naming stardards in
     # networks/physical/networks.yaml
     # NOTE: Ensure that the genesis node is manually configured with this
-    # hostname before running `genesis.sh` on the node.
+    # hostname before running `genesis.sh` on the node, see
+    # https://airship-treasuremap.readthedocs.io/en/latest/authoring_and_deployment.html#genesis-node
     hostname: pod17-node1
-    # NEWSITE-CHANGEME: Calico IP of the Genesis node. Use the "start" value for
-    # the calico network defined in networks/physical/networks.yaml for this IP.
+    # NEWSITE-CHANGEME: Address defined for Calico network in
+    # networks/physical/networks.yaml
     ip: 10.10.172.21
 
   bootstrap:
-    # NEWSITE-CHANGEME: Update with the "start" value/IP of the static range
-    # defined for the pxe network in networks/physical/networks.yaml
+    # NEWSITE-CHANGEME: Address defined for the Admin (PXE) network in
+    # networks/physical/networks.yaml
     ip: 10.10.171.21
 
   kubernetes:
@@ -81,7 +91,7 @@ data:
     container_port: 2379
     haproxy_port: 2378
 
-  # NEWSITE-CHANGEME: A list of nodes (apart from Genesis) which act as the
+  # NEWSITE-CHANGEME: A list of nodes (excluding Genesis) which act as the
   # control plane servers. Ensure that this matches the nodes with the 'masters'
   # tags applied in baremetal/nodes.yaml
   masters:
@@ -102,7 +112,6 @@ data:
   node_ports:
     drydock_api: 30000
     maas_api: 30001
-    maas_proxy: 31800  # hardcoded in MAAS
 
   ntp:
     # comma separated NTP server list. Verify that these upstream NTP servers are
@@ -110,7 +119,7 @@ data:
     # values for your environment.
     servers_joined: '0.ubuntu.pool.ntp.org,1.ubuntu.pool.ntp.org,2.ubuntu.pool.ntp.org,4.ubuntu.pool.ntp.org'
 
-  # NOTE: This will be updated soon
+  # An example for Openstack Helm Infra LDAP
   ldap:
     # NEWSITE-CHANGEME: FQDN for LDAP. Update to the FQDN that is
     # relevant for your type of deployment (test vs prod values, etc).
@@ -133,23 +142,23 @@ data:
   storage:
     ceph:
       # NEWSITE-CHANGEME: CIDRs for Ceph. Update to match the network CIDR
-      # used for the `storage` network in networks/physical/networks.yaml
+      # used for the Storage network in networks/physical/networks.yaml
       public_cidr: '10.10.173.0/24'
       cluster_cidr: '10.10.173.0/24'
 
   neutron:
-    # NEWSITE-CHANGEME: Overlay network for VM traffic. Ensure the bond name and
-    # VLAN number are consistent with what's defined for the bond and the overlay
-    # network in networks/physical/networks.yaml
+    # NEWSITE-CHANGEME: Overlay network for VM traffic. Ensure the interface name and
+    # VLAN number are consistent with what's defined for the Private network in
+    # networks/physical/networks.yaml
     tunnel_device: 'ens785f0'
-    # bond which the overlay is a member of. Ensure the bond name is consistent
-    # with the bond assigned to the overlay network in
+    # Interface for the OpenStack external network. Ensure the interface name is
+    # consistent with the interface and VLAN assigned to the Public network in
     # networks/physical/networks.yaml
     external_iface: 'ens785f1.1173'
 
   openvswitch:
-    # bond which the overlay is a member of. Ensure the bond name is consistent
-    # with the bond assigned to the overlay network in
+    # Interface for the OpenStack external network. Ensure the interface name is
+    # consistent with the interface and VLAN assigned to the Public network in
     # networks/physical/networks.yaml
     external_iface: 'ens785f1.1173'
 ...
diff --git a/site/intel-pod17/networks/physical/networks.yaml b/site/intel-pod17/networks/physical/networks.yaml
index d149b07..11329c3 100644
--- a/site/intel-pod17/networks/physical/networks.yaml
+++ b/site/intel-pod17/networks/physical/networks.yaml
@@ -1,8 +1,8 @@
 ---
 # The purpose of this file is to define all of the NetworkLinks (i.e. layer 1
-# devices) and Networks (i.e. layer 3 configurations). The following is standard
-# for the logical networks in Airship:
+# devices) and Networks (i.e. layer 3 configurations).
 #
+# The following is reference configuration for Intel hosted POD17
 # https://wiki.opnfv.org/display/pharos/Intel+POD17
 # +--------+------------+-----------------------------------+----------+----------+----------------+
 # |        |            |                                   |          |          |                |
@@ -19,11 +19,6 @@
 # NetworkLinks and Networks in this file. Only the IP addresses and CIDRs should
 # need editing.
 #
-# TODO: Given that we expect all network broadcast domains to span all racks in
-# Airship, we should choose network names that do not include the rack number.
-#
-# TODO: FQDN naming standards for hosts
-#
 schema: 'drydock/NetworkLink/v1'
 metadata:
   schema: 'metadata/Document/v1'
@@ -33,8 +28,8 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
-  # MaaS doesnt own this network like it does the others, so the noconfig label
-  # is specified.
+  # MaaS doesnt own this network like it does the others,
+  # so the noconfig label is specified.
   labels:
     noconfig: enabled
   bonding:
@@ -64,14 +59,6 @@ data:
     - subnet: '0.0.0.0/0'
       gateway: 10.10.170.1
       metric: 100
-  # NEWSITE-CHANGEME: Update with the site's out-of-band IP allocation range
-  # FIXME: Is this IP range actually used/allocated for anything? The HW already
-  # has its OOB IPs assigned. None of the Ubuntu OS's should need IPs on OOB
-  # network either, as they should be routable via the default gw on OAM network
-  ranges:
-    - type: static
-      start: 10.10.170.20
-      end: 10.10.170.39
 ...
 ---
 schema: 'drydock/NetworkLink/v1'
@@ -103,37 +90,24 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
-  # NEWSITE-CHANGEME: Update with the site's PXE network CIDR
-  # NOTE: The CIDR minimum size = (number of nodes * 2) + 10
+  # NEWSITE-CHANGEME: Update with the site's DMZ network CIDR
   cidr: 10.10.170.0/24
   routes:
     - subnet: 0.0.0.0/0
-      # NEWSITE-CHANGEME: Set the OAM network gateway IP address
+      # NEWSITE-CHANGEME: Set the DMZ network gateway IP address
+      # NOTE: This serves as the site's default route.
       gateway: 10.10.170.1
       metric: 100
-  # NOTE: The first 10 IPs in the subnet are reserved for network infrastructure.
-  # The remainder of the range is divided between two subnets of equal size:
-  # one static, and one DHCP.
-  # The DHCP addresses are used when nodes perform a PXE boot (DHCP address gets
-  # assigned), and when a node is commissioning in MaaS (also uses DHCP to get
-  # its IP address). However, when MaaS installs the operating system
-  # ("Deploying/Deployed" states), it will write a static IP assignment to
-  # /etc/network/interfaces[.d] with IPs from the "static" subnet defined here.
   ranges:
-    # NEWSITE-CHANGEME: Update to the first 10 IPs in the CIDR
+    # NEWSITE-CHANGEME: Exclude any reserved IPs for the lab.
     - type: reserved
-      start: 10.10.170.1
-      end: 10.10.170.19
-    # NEWSITE-CHANGEME: Update to the first half of the remaining range after
-    # excluding the 10 reserved IPs.
+      start: 10.10.171.1
+      end: 10.10.171.19
+    # NEWSITE-CHANGEME: Update static range that will be used for the nodes.
+    # See minimum range required for the nodes in baremetal/nodes.yaml.
     - type: static
       start: 10.10.170.20
       end: 10.10.170.39
-    # NEWSITE-CHANGEME: Update to the second half of the remaining range after
-    # excluding the 10 reserved IPs.
-    - type: dhcp
-      start: 10.10.170.40
-      end: 10.10.170.79
   dns:
     # NEWSITE-CHANGEME: FQDN for bare metal nodes.
     # Choose FQDN according to the node FQDN naming conventions at the top of
@@ -177,31 +151,29 @@ data:
   # NEWSITE-CHANGEME: Update with the site's PXE network CIDR
   # NOTE: The CIDR minimum size = (number of nodes * 2) + 10
   cidr: 10.10.171.0/24
-  # routes:
-  #   - subnet: 0.0.0.0/0
-  #     # NEWSITE-CHANGEME: Set the OAM network gateway IP address
-  #     gateway: 10.10.171.1
-  #     metric: 100
-  # NOTE: The first 10 IPs in the subnet are reserved for network infrastructure.
-  # The remainder of the range is divided between two subnets of equal size:
-  # one static, and one DHCP.
-  # The DHCP addresses are used when nodes perform a PXE boot (DHCP address gets
-  # assigned), and when a node is commissioning in MaaS (also uses DHCP to get
-  # its IP address). However, when MaaS installs the operating system
-  # ("Deploying/Deployed" states), it will write a static IP assignment to
-  # /etc/network/interfaces[.d] with IPs from the "static" subnet defined here.
+  routes:
+    - subnet: 0.0.0.0/0
+      # NEWSITE-CHANGEME: Set the Admin network gateway IP address
+      gateway: 10.10.171.1
+      metric: 100
+  # NOTE: The DHCP addresses are used when nodes perform a PXE boot
+  # (DHCP address gets assigned), and when a node is commissioning in MaaS
+  # (also uses DHCP to get its IP address). However, when MaaS installs the
+  # operating system ("Deploying/Deployed" states), it will write a static IP
+  # assignment to /etc/network/interfaces[.d] with IPs from the "static"
+  # subnet defined here.
   ranges:
-    # NEWSITE-CHANGEME: Update to the first 10 IPs in the CIDR
+    # NEWSITE-CHANGEME: Exclude any reserved IPs for the lab.
     - type: reserved
       start: 10.10.171.1
       end: 10.10.171.19
     # NEWSITE-CHANGEME: Update to the first half of the remaining range after
-    # excluding the 10 reserved IPs.
+    # excluding the reserved IPs.
     - type: static
       start: 10.10.171.20
       end: 10.10.171.39
     # NEWSITE-CHANGEME: Update to the second half of the remaining range after
-    # excluding the 10 reserved IPs.
+    # excluding the reserved IPs.
     - type: dhcp
       start: 10.10.171.40
       end: 10.10.171.79
@@ -210,8 +182,10 @@ data:
     # Choose FQDN according to the node FQDN naming conventions at the top of
     # this document.
     domain: intel-pod17.opnfv.org
-    # List of upstream DNS forwards. Verify you can reach them from your
-    # environment. If so, you should not need to change them.
+    # NEWSITE-CHANGEME: Use MAAS VIP as the DNS server.
+    # MAAS has inbuilt DNS server and Debian mirror that allows nodes to be
+    # deployed without requiring routed/internet access for the Admin/PXE interface.
+    # See data.vip.maas_vip in networks/common-addresses.yaml.
     # TODO: This should be populated via substitution from common-addresses
     servers: '10.10.171.100'
 ...
@@ -228,10 +202,7 @@ data:
   bonding:
     mode: disabled
   # NEWSITE-CHANGEME: Ensure the network switches in the environment are
-  # configured for this MTU or greater. Even if switches are configured for or
-  # can support a slightly higher MTU, there is no need (and negliable benefit)
-  # to squeeze every last byte into the MTU (e.g., 9216 vs 9100). Leave MTU at
-  # 9100 for maximum compatibility.
+  # configured for this MTU or greater.
   mtu: 1500
   linkspeed: auto
   trunking:
@@ -250,15 +221,15 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
-  # NEWSITE-CHANGEME: Set the VLAN ID which the storage network is on
+  # NEWSITE-CHANGEME: Set the VLAN ID which the Private network is on
   vlan: '0'
   mtu: 1500
-  # NEWSITE-CHANGEME: Set the CIDR for the storage network
+  # NEWSITE-CHANGEME: Set the CIDR for the Private network
   # NOTE: The CIDR minimum size = number of nodes + 10
   cidr: 10.10.172.0/24
   ranges:
-    # NEWSITE-CHANGEME: Update to the remaining range after excluding the 10
-    # 10 reserved IPs.
+    # NEWSITE-CHANGEME: Update to the remaining range excluding (if any)
+    # reserved IPs.
     - type: static
       start: 10.10.172.1
       end: 10.10.172.19
@@ -273,32 +244,18 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
-  # NEWSITE-CHANGEME: Set the VLAN ID which the OAM network is on
+  # NEWSITE-CHANGEME: Set the VLAN ID which the Management network is on
   vlan: '174'
   mtu: 1500
-  # NEWSITE-CHANGEME: Set the CIDR for the OAM network
+  # NEWSITE-CHANGEME: Set the CIDR for the Management network
   # NOTE: The CIDR minimum size = number of nodes + 10
   cidr: 10.10.174.0/24
-  routes:
-    - subnet: 0.0.0.0/0
-      # NEWSITE-CHANGEME: Set the OAM network gateway IP address
-      gateway: 10.10.174.1
-      metric: 100
   ranges:
-    # NEWSITE-CHANGEME: Update to the remaining range after excluding the 10
-    # 10 reserved IPs.
+    # NEWSITE-CHANGEME: Update to the remaining range excluding (if any)
+    # reserved IPs.
     - type: static
       start: 10.10.174.1
       end: 10.23.21.19
-  dns:
-    # NEWSITE-CHANGEME: FQDN for bare metal nodes.
-    # Choose FQDN according to the node FQDN naming conventions at the top of
-    # this document.
-    domain: intel-pod17.opnfv.org
-    # List of upstream DNS forwards. Verify you can reach them from your
-    # environment. If so, you should not need to change them.
-    # TODO: This should be populated via substitution from common-addresses
-    servers: '8.8.8.8,8.8.4.4'
 ...
 ---
 schema: 'drydock/NetworkLink/v1'
@@ -313,10 +270,7 @@ data:
   bonding:
     mode: disabled
   # NEWSITE-CHANGEME: Ensure the network switches in the environment are
-  # configured for this MTU or greater. Even if switches are configured for or
-  # can support a slightly higher MTU, there is no need (and negliable benefit)
-  # to squeeze every last byte into the MTU (e.g., 9216 vs 9100). Leave MTU at
-  # 9100 for maximum compatibility.
+  # configured for this MTU or greater.
   mtu: 1500
   linkspeed: auto
   trunking:
@@ -336,20 +290,24 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
-  # NEWSITE-CHANGEME: Set the VLAN ID which the storage network is on
+  # NEWSITE-CHANGEME: Set the VLAN ID which the Storage network is on
   vlan: '0'
+  # NEWSITE-CHANGEME: Ensure the network switches in the environment are
+  # configured for this MTU or greater.
   mtu: 1500
-  # NEWSITE-CHANGEME: Set the CIDR for the storage network
+  # NEWSITE-CHANGEME: Set the CIDR for the Storage network
   # NOTE: The CIDR minimum size = number of nodes + 10
   cidr: 10.10.173.0/24
   ranges:
-    # NEWSITE-CHANGEME: Update to the remaining range after excluding the 10
-    # 10 reserved IPs.
+    # NEWSITE-CHANGEME: Update to the remaining range excludin (if any)
+    # reserved IPs.
     - type: static
       start: 10.10.173.1
       end: 10.10.173.19
 ...
 ---
+# The public network for OpenStack VMs.
+# NOTE: Only interface 'ens785f1.1173' will be setup, no IPs assigned to hosts
 schema: 'drydock/Network/v1'
 metadata:
   schema: 'metadata/Document/v1'
@@ -359,7 +317,11 @@ metadata:
     layer: site
   storagePolicy: cleartext
 data:
+  # NEWSITE-CHANGEME: Set the VLAN ID which the Public network is on
   vlan: '1173'
+  # NEWSITE-CHANGEME: Ensure the network switches in the environment are
+  # configured for this MTU or greater.
   mtu: 1500
+  # NEWSITE-CHANGEME: Set the CIDR for the Public network
   cidr: 10.10.175.0/24
 ...