Review of provisioning and lifecycle chapters

- lint fixes (links, spelling, etc.)

Author: Zack Williams

dict.txt

@@ -47,6 +47,8 @@ Netplan
 Nginx
 Nicira
 ONOS
+Oauth
+Observability
 Oguz
 Onos
 POD
@@ -62,12 +64,12 @@ Repo
 Repos
 Runtime
 SDN
-Sami
 Sigelman
 Suchitra
 Sunay
 Sys
 Syslog
+Sámi
 Tanzu
 Telco
 Telcos
@@ -132,7 +134,6 @@ mindshare
 namespaces
 natively
 observability
-Observability
 onos
 operationalization
 operationalize
@@ -156,22 +157,23 @@ rollout
 rst
 runtime
 runtimes
-scalable
 scalability
+scalable
 signalling
 stderr
 stdin
 stdout
 storylines
-subnet
 subcomponents
+subnet
 systemsapproach
 textboxes
 todo
 todolist
 toolchain
 toolset
 untrusted
+unwinnable
 uplink
 uptime
 virtualenv

intro.rst

@@ -50,7 +50,7 @@ available open source software packages.
   leverage, developers do not need to (and should not) reinvent the
   wheel when it comes to provisioning, configuring, controlling, and
   monitoring the services they implement.*
-  
+
   *Looking at the broader picture, this management platform is an
   essential part of how app builders and service developers deliver
   functionality to end users. Today, functionality is most often
@@ -693,19 +693,19 @@ service meshes in our discussion of observability in Chapter 6.
   adopting a bundled solution, understanding all the trade-offs being
   made under the covers will help to make a more informed decision.*
 
-Second, we assume a container-based cloud platform. An alternative 
-would have been VM-based. The main reason for this choice is that 
-containers are rapidly becoming the de facto way to deploy scalable 
-and highly available functionality, and operationalizing such 
-functionality in enterprises is our primary use case. Containers are 
-sometimes deployed inside of VMs (rather than directly on physical 
-machines), but in that case, the VMs can be viewed as part of the 
-underlying infrastructure (rather than a service that is offered to 
-users). Another way of saying this is that this book focuses on how to 
+Second, we assume a container-based cloud platform. An alternative
+would have been VM-based. The main reason for this choice is that
+containers are rapidly becoming the de facto way to deploy scalable
+and highly available functionality, and operationalizing such
+functionality in enterprises is our primary use case. Containers are
+sometimes deployed inside of VMs (rather than directly on physical
+machines), but in that case, the VMs can be viewed as part of the
+underlying infrastructure (rather than a service that is offered to
+users). Another way of saying this is that this book focuses on how to
 operationalize a Platform-as-a-Service (PaaS) rather than an
-Infrastructure-as-a-Service (IaaS), although later chapters will 
-describe how to introduce VMs as an optional way to provision the 
-underlying infrastructure for that PaaS. 
+Infrastructure-as-a-Service (IaaS), although later chapters will
+describe how to introduce VMs as an optional way to provision the
+underlying infrastructure for that PaaS.
 
 Finally, the Aether edge cloud we use as an example is similar to many
 other edge cloud platforms now being promoted as an enabling
@@ -720,10 +720,10 @@ platform, along with all the cloud services that run on top of it, are
 managed as a whole. The Aether example allows us to be specific, but
 hopefully not at the expense of general applicability.
 
-.. admonition:: Further Reading 
+.. admonition:: Further Reading
 
-   `Smart Edge Open 
-   <https://www.openness.org/>`__. 
+   `Smart Edge Open
+   <https://smart-edge-open.github.io/>`__.
 
 1.4 Future of the Sysadmin
 --------------------------

monitor.rst

@@ -442,7 +442,7 @@ foreseeable future.
    `OpenTelemetry: High-quality, ubiquitous, and portable telemetry to
    enable effective observability <https://opentelemetry.io/>`__.
 
-   `Jaeger: End-to-End Distributed Tracing 
+   `Jaeger: End-to-End Distributed Tracing
    <https://www.jaegertracing.io/>`__.
 
 With respect to mechanisms, Jaeger is a widely used open source
@@ -576,7 +576,7 @@ about INT, we refer the reader to our companion SDN book.
 .. admonition:: Further Reading
 
    L. Peterson, *et al.* `Software-Defined Networking: A Systems Approach
-   <https://sdn.sysetmsapproach.org>`__. November 2021.
+   <https://sdn.systemsapproach.org>`__. November 2021.
 
 The second is the emergence of *Service Meshes* mentioned in
 Chapter 1. A Service Mesh framework such as Istio provides a means to
@@ -600,7 +600,7 @@ receiving security directives from a global policy engine.
    messages flowing between Services A and B. Each sidecar enforces
    security policy received from the central controller and sends
    telemetry data to the central controller.
-	   
+
 From the perspective of observability, sidecars can be programmed to
 record whatever information operators might want to collect, and in
 principle, they can even be dynamically updated as conditions warrant.

preface.rst

@@ -69,8 +69,7 @@ applications manageable and reliable. There is increasingly close
 interaction between developers and operators (as evidenced by the
 DevOps movement) and we aim to facilitate that collaboration. Topics
 such as monitoring and observability are particularly important for
-this audience. 
-
+this audience.
 
 Guided Tour of Open Source
 --------------------------

provision.rst

@@ -66,7 +66,6 @@ focus on the challenge of provisioning an entire site the first time.
 We comment on the simpler problem of incrementally provisioning
 individual resources as relevant details emerge.
 
-
 3.1 Physical Infrastructure
 ---------------------------
 
@@ -130,8 +129,8 @@ information is readily available on the NetBox web site.
 .. _reading_netbox:
 .. admonition:: Further Reading
 
-   `NetBox: <https://netbox.readthedocs.io/en/stable>`_ Information
-   Resource Modeling Application.
+   `NetBox: <https://docs.netbox.dev>`_ Information Resource Modeling
+   Application.
 
 One of the key features of NetBox is the ability to customize the set
 of models used to organize all the information that is collected. For
@@ -234,22 +233,23 @@ The following fields are also filled in when creating a Device:
 * MAC Addresses
 
 Note there is typically both a primary and management (e.g., BMC/IPMI)
-interface, where the *Device Type* implies the specific interfaces.
+interface. One convenience feature of Netbox is to use the *Device Type* as a
+template that will set the default naming of interfaces, power connections, and
+other equipment model specific characteristics.
 
-Finally, the virtual interfaces for the Device must be specified, with
-its *Label* field set to the physical network interface that it is
-assigned. IP addresses are then assigned to the physical and virtual
-interfaces we have defined. The Management Server should always have
-the first IP address in each range, and they should be incremental, as
-follows:
+Finally, the virtual interfaces for the Device must be specified, with its
+*Label* field set to the physical network interface that it is assigned. IP
+addresses are then assigned to the physical and virtual interfaces we have
+defined. The Management Server should always have the first IP address within
+each prefix, and by convention they are assigned incrementally as follows:
 
 * Management Server
 
   * ``eno1`` - site provided public IP address, or blank if DHCP provided
   * ``eno2`` - 10.0.0.1/25 (first of ADMIN) - set as primary IP
   * ``bmc`` - 10.0.0.2/25 (next of ADMIN)
-  * ``mgmt800`` - 10.0.0.129/25 (first of MGMT)
-  * ``fab801`` - 10.0.1.1/25 (first of FABRIC)
+  * ``mgmt800`` - 10.0.0.129/25 (first of MGMT, on VLAN 800)
+  * ``fab801`` - 10.0.1.1/25 (first of FABRIC, on VLAN 801)
 
 * Management Switch
 
@@ -323,7 +323,7 @@ deployment currently include:
 
 * Configure the Management Server so it boots from a provided USB key.
 
-* Load Ansible roles and playbooks needed to complete configuration
+* Run Ansible roles and playbooks needed to complete configuration
   onto the Management Server.
 
 * Configure the Compute Servers so they boot from the Management
@@ -345,8 +345,13 @@ should be taken to *not* overload this step with configuration that
 can be done later. For example, various radio parameters can be set on
 the eNBs when it is physically installed, but those parameters will
 become settable through the Management Platform once the cluster is
-brought online. Configuration work done at this stage should be
-minimized.
+brought online.
+
+Manual configuration work done at this stage should be minimized, and most
+systems should be configured to use automated means of configuration. For
+example, using DHCP pervasively with MAC reservations for IP address assignment
+instead of manual configuration of each interface allows for management to be
+Zero Touch and simplifies future reconfiguration.
 
 The automated aspects of configuration are implemented as a set of
 Ansible *roles* and *playbooks*, which in terms of the high-level
@@ -359,30 +364,32 @@ parameters that NetBox maintains.
 
 The general idea is as follows. For every network service (e.g., DNS,
 DHCP, iPXE, Nginx) and every per-device subsystem (e.g., network
-interfaces, Docker) that needs to be configured, there is a
-corresponding Ansible role and playbook.\ [#]_ This set is copied onto
-the Management Server during the manual configuration stage summarized
-above, and then executed once the management network is online.
+interfaces, Docker) that needs to be configured, there is a corresponding
+Ansible role and playbook.\ [#]_ These configurations are applied to the
+Management Server during the manual configuration stage summarized above, once
+the management network is online.
 
 .. [#] We gloss over the distinction between *roles* and *playbooks*
        in Ansible, and focus on the general idea of there being a
        *script* that runs with a set of input parameters.
 
-The Ansible playbooks instantiate the network services on the
-Management Server. The role of DNS and DHCP are obvious. As for iPXE
-and Nginx, they are boot servers for the rest of the infrastructure:
-the compute servers are configured to boot from the former and the
-fabric switches are configured to boot from the latter.
+The Ansible playbooks install and configure the network services on the
+Management Server. The role of DNS and DHCP are obvious. As for iPXE and Nginx,
+they are used to bootstrap the rest of the infrastructure: the compute servers
+are configured by iPXE delivered over DHCP/TFTP, then loading the scripted OS
+installation from a Nginx webserver, and the fabric switches receive their
+Stratum OS package from a webserver.
 
 In many cases, the playbooks use parameters—such as VLANs, IP
 addresses, DNS names, and so on—extracted from NetBox. :numref:`Figure
 %s <fig-ansible>` illustrates the approach, and fills in a few
 details. For example, a home-grown Python program (``edgeconfig.py``)
-extracts data from NetBox and outputs a corresponding set of YAML
-files, crafted to serve as input to yet another open source tool
-(*Netplan*), which actually does the detailed work of configuring the
-network subsystem on the various backend devices. More information
-about Ansible and Netplan is available on their respective web sites.
+extracts data from NetBox using the REST API and outputs a corresponding
+set of YAML files, crafted to serve as input to Ansible, which creates yet
+more configuration on management and compute systems.  One example of this
+is the *Netplan* file, which is used in Ubuntu to manage network interfaces.
+More information about Ansible and Netplan can be found on their respective web
+sites.
 
 .. _reading_ansible:
 .. admonition:: Further Reading