Update documentation comments in site manfiests

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

1 files changed, 33 insertions, 24 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'
 ...