Updating the site planning documention
Change-Id: Icdcf67081407df5aa30ae9ae67b0af9207c75c1e
diff --git a/edge_deployment/site_planning.rst b/edge_deployment/site_planning.rst
index 4af68f7..7973eda 100644
--- a/edge_deployment/site_planning.rst
+++ b/edge_deployment/site_planning.rst
@@ -8,28 +8,35 @@
Site Design in Netbox
---------------------
+The Aether project uses Netbox as source of truth, and the automation script uses
+it's API to create input files for Ansible Playbooks which are used to configure
+each site.
+
Once the hardware has been ordered, the installation can be planned. The
following information needs to be added to `NetBox
<https://netbox.readthedocs.io/en/stable>`_ to describe each edge site:
-1. Add a Site for the edge (if one doesn't already exist), which has the
- physical location and contact information for the edge.
+.. note::
+ The **bold** words represent the models in Netbox.
+
+1. Add a **Site** for the edge (if one doesn't already exist), which has the
+ physical location and contact information for the Aether Edge.
2. Add equipment Racks to the Site (if they don't already exist).
-3. Add a Tenant for the edge (who owns/manages it), assigned to the ``Pronto``
+3. Add a **Tenant** for the edge (who owns/manages it), assigned to the ``Pronto``
or ``Aether`` Tenant Group.
-4. Add a VRF (Routing Table) for the edge site. This is usually just the name
+4. Add a **VRF** (Routing Table) for the edge site. This is usually just the name
of the site. Make sure that ``Enforce unique space`` is checked, so that IP
addresses within the VRF are forced to be unique, and that the Tenant Group
and Tenant are set.
-5. Add a VLAN Group to the edge site, which groups the site's VLANs and
+5. Add a **VLAN Group** to the edge site, which groups the site's VLANs and
requires that they have a unique VLAN number.
-6. Add VLANs for the edge site. These should be assigned a VLAN Group, the
- Site, and Tenant.
+6. Add **VLANs** for the edge site. These VLAN objects should be assigned a VLAN
+ Group, a Site, and a Tenant.
There can be multiple of the same VLAN in NetBox (VLANs are layer 2, and
local to the site), but not within the VLAN group.
@@ -42,53 +49,63 @@
* FAB 801
If you have multiple deployments at a site using the same management server,
- add additional VLANs incremented by 10 for the MGMT/FAB - for example:
+ add additional VLANs incremented by 10 for the MGMT/FAB - for example, you
+ can create the VLANs for development server as follows:
* DEVMGMT 810
* DEVFAB 801
-7. Add IP Prefixes for the site. This should have the Tenant and VRF assigned.
+7. Add IP **Prefixes** for the site. This should have the Tenant and VRF assigned.
- All edge IP prefixes fit into a ``/22`` sized block.
+ All IP prefixes of Aether Edge will fit into a ``/22`` sized block.
- The description of the Prefix contains the DNS suffix for all Devices that
- have IP addresses within this Prefix. The full DNS names are generated by
- combining the first ``<devname>`` component of the Device names with this
- suffix.
+ The Prefix description field is used to create DNS names for IP addresses in the Prefix.
+ The DNS A records for each IP address start with the name of the Device, and end with
+ the Prefix description.
- An examples using the ``10.0.0.0/22`` block. There are 4 edge
- prefixes, with the following purposes:
+ For example, if we have a management server named ``mgmtserver`` in **Prefix**
+ ``prod1.menlo.aetherproject.net``, and the management server's DNS name will be
+ ``mgmtserver.prod1.menlo.aetherproject.net``.
- * ``10.0.0.0/25``
+ Here is an example using the ``10.0.0.0/22`` block. Let's name our deployment
+ as "prod1", and name our site as "menlo". Then we define 4 **Prefixes**
+ with different purposes.
+
+.. note::
+ NOTE: You should replace the **prod1** and **menlo** to your deployment name and
+ site name.
+..
+
+ * ADMIN Prefix - ``10.0.0.0/25`` (for Lights-out management)
* Has the Server BMC/LOM and Management Switch
- * Assign the ADMIN 1 VLAN
- * Set the description to ``admin.<deployment>.<site>.aetherproject.net`` (or
+ * Assign with the ADMIN 1 VLAN
+ * Set the description to ``admin.prod1.menlo.aetherproject.net`` (or
``prontoproject.net``).
- * ``10.0.0.128/25``
+ * MGMT Prefix - ``10.0.0.128/25`` (for infrastructure control plane)
* Has the Server Management plane, Fabric Switch Management/BMC
- * Assign MGMT 800 VLAN
- * Set the description to ``<deployment>.<site>.aetherproject.net`` (or
+ * Assign with MGMT 800 VLAN
+ * Set the description to ``prod1.menlo.aetherproject.net`` (or
``prontoproject.net``).
- * ``10.0.1.0/25``
+ * FABRIC1 Prefix - ``10.0.1.0/25``
- * IP addresses of the qsfp0 port of the Compute Nodes to Fabric switches, devices
- connected to the Fabric like the eNB
+ * Compute Nodes' qsfp0 port which connects to Fabric switches,
+ and other devices (eNB, ...) connect to the Fabric switches.
+ * Assign with FAB 801 VLAN
+ * Set the description to ``fab1.prod1.menlo.aetherproject.net`` (or
+ ``prontoproject.net``).
+
+ * FABRIC2 Prefix - ``10.0.1.128/25``
+
+ * Compute Nodes' qsfp1 port which connects to Fabric switches
* Assign FAB 801 VLAN
- * Set the description to ``fab1.<deployment>.<site>.aetherproject.net`` (or
+ * Set the description to ``fab2.prod1.menlo.aetherproject.net`` (or
``prontoproject.net``).
- * ``10.0.1.128/25``
-
- * IP addresses of the qsfp1 port of the Compute Nodes to fabric switches
- * Assign FAB 801 VLAN
- * Set the description to ``fab2.<deployment>.<site>.aetherproject.net`` (or
- ``prontoproject.net``).
-
- There also needs to be a parent range of the two fabric ranges added:
+ And we will have an additional parent prefix includes 2 FABRIC Prefix.
* ``10.0.1.0/24``
@@ -108,7 +125,7 @@
* Kubernetes Cluster IP's
-8. Add Devices to the site, for each piece of equipment. These are named with a
+8. Add **Devices** to the site, for each piece of equipment. These are named with a
scheme similar to the DNS names used for the pod, given in this format::
<devname>.<deployment>.<site>
@@ -135,7 +152,7 @@
See `Rackmount of Equipment`_ below for guidance on how equipment should be
mounted in the Rack.
-9. Add Services to the management server:
+9. Add **Service** to the management server:
* name: ``dns``
protocol: UDP
@@ -150,29 +167,29 @@
10. Set the MAC address for the physical interfaces on the device.
- You may also need to add physical network interfaces if aren't already
+ You may also need to add physical network interfaces if they aren't already
created by the Device Type. An example would be if additional add-in
network cards were installed.
-11. Add any virtual interfaces to the Devices. When creating a virtual
- interface, it should have it's ``label`` field set to the physical network
- interface that it is assigned
+11. Add any virtual interfaces to the **Devices**. When creating a virtual
+ interface, it should have it's ``label`` field set to the name of the
+ physical interface that it is assigned
- These are needed are two cases for the Pronto deployment:
+ These are needed for two cases of the Pronto deployment:
1. On the Management Server, there should bet (at least) two VLAN
interfaces created attached to the ``eno2`` network port, which
are used to provide connectivity to the management plane and fabric.
- These should be named ``<name of vlan><vlan ID>``, so the MGMT 800 VLAN
- would become a virtual interface named ``mgmt800``, with the label
- ``eno2``.
+ These interfaces should be named ``<name of vlan><vlan ID>``, so the
+ MGMT 800 VLAN would become a virtual interface named ``mgmt800``, with
+ the label ``eno2``.
2. On the Fabric switches, the ``eth0`` port is shared between the OpenBMC
interface and the ONIE/ONL installation. Add a ``bmc`` virtual
- interface with a label of ``eth0`` on each fabric switch, and check the
- ``OOB Management`` checkbox.
+ interface with a label of ``eth0`` on each fabric switch, and have the
+ ``OOB Management`` checkbox checked.
-12. Create IP addresses for the physical and virtual interfaces. These should
+12. Create **IP addresses** for the physical and virtual interfaces. These should
have the Tenant and VRF set.
The Management Server should always have the first IP address in each
@@ -210,17 +227,18 @@
* ``eth0`` or other primary interface - 10.0.1.4/25 (next of FAB)
-13. Add DHCP ranges to the IP Prefixes for IP's that aren't reserved. These are
- done like any other IP Address, but with the ``Status`` field is set to
- ``DHCP``, and they'll consume the entire range of IP addresses given in the
- CIDR mask.
+13. Add **IP address** to the **Prefix** to represent reserved DHCP ranges.
+ We use a single IP address which ``Status`` is set to ``DHCP`` to stand
+ for the DHCP range, the DHCP server will consume the entire range of IP
+ address in the CIDR mask (includes first and last IP addresses).
- For example ``10.0.0.32/27`` as a DHCP block would take up 1/4 of the ADMIN
- prefix.
+ For example, IP ``10.0.0.32/27`` with ``DHCP`` status in Prefix
+ ``10.0.0.0/25``, the IP will be a DHCP block, and allocate IP address from
+ ``10.0.0.32`` to ``10.0.0.63``.
-14. Add router IP reservations to the IP Prefix for both Fabric prefixes. These
- are IP addresses used by ONOS to route traffic to the other leaf, and have
- the following attributes:
+14. Add **IP address** to the **Prefix** to represent route IP reservations for
+ both Fabric prefixes. These are IP addresses used by ONOS to route traffic
+ to the other leaf, and have the following attributes:
- Have the last usable address in range (in the ``/25`` fabric examples
above, these would be ``10.0.1.126/25`` and ``10.0.1.254/25``)