Add challenges, add specifc anchors to cross references, correct quic…

…kstart cli hyperlink

docs/concepts.md

@@ -33,6 +33,8 @@ deeper into detail.
    time determining what changed for a particular version - KubeFox handles that
    automatically.
 
+   : Systems map 1:1 with repositories.
+
 #### **`Repository`**
 
    : A repository is a Git repository. Repositories map 1:1 with Systems.

docs/deployment_distillation.md

@@ -1,11 +1,18 @@
 <!-- markdownlint-disable MD033 -->
 # Deployment Distillation
 
-KubeFox automatically distills System Deployments to only those components that are new or which have changed.  You can think of this process as a diff between what components are currently running in the cluster, and what components have changed in the new deployment.  In so doing KubeFox helps you control provisioning.
+KubeFox automatically distills System Deployments to only those components that
+are new or which have changed.  You can think of this process as a diff between
+what components are currently running in the cluster, and what components have
+changed in the new deployment.  In so doing KubeFox helps you control
+provisioning.
 
 For purposes of illustration, consider an Order [**System**](concepts.md).
 
-Note: There are additional things happening during these deployment cycles which are discussed toward the bottom of the page. For this part of the discussion, we're contemplating multiple deployments where only the most-recently deployed version of the System is running.
+Note: There are additional things happening during these deployment cycles which
+are discussed toward the bottom of the page. For this part of the discussion,
+we're contemplating multiple deployments where only the most-recently deployed
+version of the System is running.
 
 In our scenario, there is an Order System that comprises 2 applications:
 
@@ -17,7 +24,9 @@ The Fulfillment app is composed of 4 components, 2 of which are adapters:
 1. CRON adapter
 2. State Store adapter
 
-**[Adapters](concepts.md)** are Brokers for External Components, in this case serving to proxy events, requests and responses to CRON and a State Store (like a database).
+**[Adapters](concepts.md)** are Brokers for External Components, in this case
+serving to proxy events, requests and responses to CRON and a State Store (like
+a database).
 
 The user-written components are:
 
@@ -48,7 +57,9 @@ deployment), it will look like this in KubeFox (Figure 1):
   <figcaption>Figure 1 - Initial Deployment [a]</figcaption>
 </figure>
 
-KubeFox will spool up 3 Pods, the Worker[a], api-srv[a] and the order-ui[a]. Because the api-srv component is shared by the fulfillment and web-ui apps, KubeFox will deploy it only once.
+KubeFox will spool up 3 Pods, the Worker[a], api-srv[a] and the order-ui[a].
+Because the api-srv component is shared by the fulfillment and web-ui apps,
+KubeFox will deploy it only once.
 
 ## Deployment b
 
@@ -63,7 +74,9 @@ System b is deployed, it will look as shown in Figure 2:
   <figcaption>Figure 2 - Deployment [b] to change the order-ui component</figcaption>
 </figure>
 
-Note that in our deployment table, only the order-ui component was deployed. KubeFox checks the state of the Order System and deploys only the components that have changed.
+Note that in our deployment table, only the order-ui component was deployed.
+KubeFox checks the state of the Order System and deploys only the components
+that have changed.
 
 ## Deployment c
 
@@ -77,7 +90,8 @@ api-srv[c]:
   <figcaption>Figure 3 - Deployment [c] to change the api-srv component</figcaption>
 </figure>
 
-Note that the highest component version is tracked in the System (now [c]), and in the applications (now [c] as well).
+Note that the highest component version is tracked in the System (now [c]), and
+in the applications (now [c] as well).
 
 ## Deployment d
 
@@ -94,7 +108,9 @@ When the System is deployed, it looks as shown in Figure 4:
   <figcaption>Figure 4 - Deployment [d] to add a component and modify order-ui</figcaption>
 </figure>
 
-Only the new (reviews) and modified component (order-ui) are deployed. Only the web-ui application was modified - so now it's at version [d], while the fulfillment app was not modified - so it's still at version [c].
+Only the new (reviews) and modified component (order-ui) are deployed. Only the
+web-ui application was modified - so now it's at version [d], while the
+fulfillment app was not modified - so it's still at version [c].
 
 ## Summary Notes
 
@@ -103,8 +119,10 @@ There are a number things of note here:
 - To put a fine point on it, each of the deployments is a version in KubeFox.
 - All of the deployments (a - d) are actually available via explicit URLs (unless they're deprecated).
 - Systems are released monolithically - which greatly simplifies deployent for users. Under the covers KubeFox is doing a few things:
-  - Distilling the component set to the minimum required to run the new
-    deployment, thereby preserving resources and preventing over-provisioning
-  - Shaping traffic dynamically to enable the use of shared, common components both within a release (for instance, same component inside different applications) and across versions (for instance, same component version used for different deployments)
+  - Distilling the component set to the minimum required to run the new deployment, thereby preserving resources and preventing over-provisioning
+  - Shaping traffic dynamically to enable the use of shared, common components
+    both within a release (for instance,same component inside different
+    applications) and across versions (for instance, same component version used
+    for different deployments)
 - Only one copy of api-srv will be running at any given time _unless_ there is a different version of api-srv deployed for one of the apps. In that case, KubeFox will run the appropriate versions of api-srv to service requests for each individual application.
 - Default traffic will be routed to the most recently released version. So if [b] is released, default traffic will be running through version b even after version d is deployed. That provides development, QA and release teams with a great deal of power and flexibility.

docs/dynamic_routing.md

@@ -3,4 +3,4 @@
 
 KubeFox can achieve the capabilities described in [**Virtual Environments**](virtual_environments.md) and [**Versioned Deployments**](versioned_deployments.md) because it dynamically routes requests at runtime.  
 
-When requests originate - [**Genesis Events**](concepts.md) in KubeFox – metadata is associated with them that informs the KubeFox runtime how the requests should be routed.  This occurs not only at origination time, but throughout the System and for all components that are part of that System.  In so doing, KubeFox can guarantee delivery of requests to the correct version of each component, irrespective of the number of versions of that component that may be running.
+When requests originate - [**Genesis Events**](concepts.md#genesis-events) in KubeFox – metadata is associated with them that informs the KubeFox runtime how the requests should be routed.  This occurs not only at origination time, but throughout the System and for all components that are part of that System.  In so doing, KubeFox can guarantee delivery of requests to the correct version of each component, irrespective of the number of versions of that component that may be running.

docs/kubernetes_challenges.md

@@ -0,0 +1,20 @@
+# Challenges in Kubernetes
+
+It’s one thing but it’s a really big thing:  the lifecycle of software in the
+Kubernetes world is fraught with complexity and requires continual analysis and
+realignment.  And as a company and its teams grow, those difficulties increase
+disproportionately.  
+
+That analysis is performed by the scarcest and one of the most expensive teams
+in any company:  DevOps.  DevOps needs to address a variety of overlapping goals
+and deal with sometimes competing objectives:
+
+- Providing a frictionless workflow to engineering, to enable rapid prototyping and iterations
+- Application security, with the clear objective being zero trust
+- Application monitoring, testing and debugging
+- What tools will be chosen, how they’ll be implemented, provisioned, monitored and supported
+- Microservice and Pod proliferation - and resultant and continuous increases in costly resources (compute, memory, storage)
+- Providing for n - 1, n and n + 1 versions in multiple environments - a challenge magnified in dev, where the need to provide isolation results in drastic increases in resource demands
+- Dealing with multiple vendors on a discrete basis for licenses, support contracts, maintenance and upgrades
+
+… and this is just the tip of the iceberg

docs/quickstart.md

@@ -8,7 +8,7 @@ The following tools must be installed for this quickstart:
 - [Docker](https://docs.docker.com/engine/install/) - A container toolset and
   runtime. Used to build KubeFox Components' OCI images and run a local
   Kubernetes cluster via Kind.
-- [Fox CLI](https://github.com/xigxog/kubefox-cli/releases/tag/v0.1.0-alpha) -
+- [Fox CLI](https://github.com/xigxog/kubefox-cli/releases/) -
   CLI for communicating with the KubeFox Platform. Download the latest release
   and put the binary on your path.
 - [Helm](https://helm.sh/docs/intro/install/) - Package manager for Kubernetes.

docs/virtual_environments.md

@@ -49,7 +49,10 @@ KubeFox takes care of routing the requests correctly and injecting the appropria
 
 One way to think about it is that the developer environments are spooled up in seconds.  But what is really happening is that the environment is overlaid onto a deployment, and routing is dynamic.  Because KubeFox abstracts the configuration from the deployment, teams can easily and simply shift their workloads - including for deployments that have already occurred.
 
-KubeFox segregates the developer sandboxes while leveraging its capabilities to distill the number of Pods running to only those that are unique and necessary (this is discussed in greater depth in [**Versioned Deployments**](versioned_deployments.md).
+KubeFox segregates the developer sandboxes while leveraging its capabilities to
+distill the number of Pods running to only those that are unique and necessary
+(this is discussed in greater depth both in [**Versioned
+Deployments**](versioned_deployments.md) and [**Deployment Distillation**](deployment_distillation.md).
 
 In Figure 4, we have a complex Retail System comprising 3 applications (a Web UI
 app, a Catalog app and a Fulfillment app), 2 components that are shared amongst

docs/why_kubefox.md

@@ -12,7 +12,7 @@ At a high level, they’re all some variation of Figure 1 below:
 
 KubeFox automates significant parts of this workflow.
 
-In KubeFox, you build and deploy [**Systems**](concepts.md).  A **System** is simply a collection of [**Applications**](concepts.md), and applications are collections of [**Components**](concepts.md).  Components can be microservices or functions.  
+In KubeFox, you build and deploy [**Systems**](concepts.md#system).  A **System** is simply a collection of [**Applications**](concepts.md#applications), and applications are collections of [**Components**](concepts.md#components).  Components can be microservices or functions.  
 
 The System construct exists for a few reasons:
 

mkdocs.yaml

@@ -8,16 +8,17 @@ site_author: John Long
 copyright: Copyright © XigXog
 
 nav:
-  - index.md
-  - quickstart.md
+  - 'Overview': 'index.md'
+  - 'Quickstart': 'quickstart.md'
+  - 'Challenges in Kubernetes': 'kubernetes_challenges.md'
   - 'Why KubeFox?': 'why_kubefox.md'
-  - concepts.md
-  - design.md
+  - 'Concepts': 'concepts.md'
+  - 'Design': 'design.md'
+  - 'Versioned Deployments': 'versioned_deployments.md'
   - 'Deployment Distillation': 'deployment_distillation.md'
   - 'Dynamic Routing': 'dynamic_routing.md'
-  - 'Versioned Deployments': 'versioned_deployments.md'
   - 'Virtual Environments': 'virtual_environments.md'
-  - telemetry.md
+  - 'Telemetry': 'telemetry.md'
   - Reference:
       - reference/events.md
       - reference/api.md