Content and Formatting Changes to Knative Kubernetes Services (#1522)

docs/serving/knative-kubernetes-services.md

@@ -5,25 +5,36 @@ weight: 9
 type: "docs"
 ---
 
-This document describes what is running when running knative serving.
+This guide describes the [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/) that are active when running Knative Serving.
 
-After applying the serving yaml, this will install a few knative services and
-deployments on your kubernetes cluster. This document provides an overview of
-the deployments and the motivations for each one.
+## Before You Begin
 
-```sh
-$ kubectl get services -n knative-serving
+1. This guide assumes that you have installed Knative Serving. If you have not,
+   instructions on how to do this are located [here](https://knative.dev/docs/install/knative-custom-install/).
+2. Verify that you have the proper components in your cluster. To view the services installed in your cluster, use the commmand:
 
+   ```sh
+   $ kubectl get services -n knative-serving
+   ```
+
+   This should return the following output:
+
+   ```sh
 NAME                TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                  AGE
 activator-service   ClusterIP   10.96.61.11      <none>        80/TCP,81/TCP,9090/TCP   1h
 autoscaler          ClusterIP   10.104.217.223   <none>        8080/TCP,9090/TCP        1h
 controller          ClusterIP   10.101.39.220    <none>        9090/TCP                 1h
 webhook             ClusterIP   10.107.144.50    <none>        443/TCP                  1h
 ```
+ 3. To view the deployments in your cluster, use the following command:
+
+    ```sh
+    $ kubectl get deployments -n knative-serving
+    ```
 
-```sh
-$ kubectl get deployments -n knative-serving
+    This should return the following output:
 
+     ```sh
 NAME                     DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
 activator                1         1         1            1           1h
 autoscaler               1         1         1            1           1h
@@ -33,41 +44,40 @@ networking-istio         1         1         1            1           1h
 webhook                  1         1         1            1           1h
 ```
 
-## Service: activator
+These services and deployments are installed by the `serving.yaml` file during install. The next section describes their function.
+
+## Components
+
+### Service: activator
 
-The responsibilities of the activator are:
+The activator is responsible for receiving & buffering requests for inactive revisions and reporting metrics to the autoscaler. It also retries requests to a revision after the autoscaler scales the revision based on the reported metrics.
 
-- Receiving & buffering requests for inactive Revisions.
-- Reporting metrics to the autoscaler.
-- Retrying requests to a Revision after the autoscaler scales such Revision
-  based on the reported metrics.
+### Service: autoscaler
 
-## Service: autoscaler
+The autoscaler receives request metrics and adjusts the number of pods required to handle the load of traffic.
 
-The autoscaler receives request metrics and adjusts the number of pods required
-to handle the load of traffic.
+### Service: controller
 
-## Service: controller
+The controller service reconciles all the public Knative objects and autoscaling
+CRDs. When a user applies a Knative service to the Kubernetes API, this creates
+the configuration and route. It will convert the configuration into revisions and the revisions into deployments and Knative Pod Autoscalers (KPAs).
 
-The controller service reconciles all the public knative objects and autoscaling
-CRDs. When a user applies a knative service to the kubernetes api, this creates
-the config and route. It will convert config into revisions. It will convert
-Revision into Deployment and KPA.
+### Service: webhook
 
-## Service: webhook
+The webhook intercepts all Kubernetes API calls as well as all CRD insertions and updates.
+It sets default values, rejects inconsitent and invalid objects, and validates and mutates Kubernetes API calls.
 
-The webhook intercepts all kubernetes api calls, all crd insertions and updates.
-It does two things:
+### Deployment: networking-certmanager
 
-1. Set default values
-2. Rejects inconsitent and invalid objects.
+The certmanager reconciles cluster ingresses into cert manager objects.
 
-It validates and mutates k8s api calls.
+### Deployment: networking-istio
 
-## Deployment: networking-certmanager
+The networking-istio deployment reconciles a cluster's ingress into an [Istio virtual service](https://istio.io/docs/reference/config/networking/v1alpha3/virtual-service/).
 
-The certmanager reconciles cluster ingress into cert manager objects.
+## What's Next
 
-## Deployment: networking-istio
+- For a deeper look at the services and deployments involved in Knative Serving, click [here](https://github.com/knative/serving/blob/master/docs/spec/overview.md#service).
+- For a high-level analysis of Serving, look at the [documentation here](./).
+- Check out the Knative Seriving code samples [here](./samples/) for more hands-on tutorials.
 
-This reconciles cluster ingress into a virtual service.