Merge pull request #621 from drnic/docs-controllers-cleanup

[docs] formatting cleanup of controllers section

docs/controllers/boshdeployment.md

@@ -28,7 +28,7 @@ The ops files modify the deployment manifest. For example, ops files can be used
 A deployment is represented by the `boshdeployments.fissile.cloudfoundry.org` (`bdpl`) custom resource, defined in [`boshdeployment_crd.yaml`](https://github.com/cloudfoundry-incubator/cf-operator/tree/master/deploy/helm/cf-operator/templates/fissile_v1alpha1_boshdeployment_crd.yaml).
 This [bdpl custom resource](https://github.com/cloudfoundry-incubator/cf-operator/tree/master/docs/examples/bosh-deployment/boshdeployment.yaml) contains references to config maps or secrets containing the actual manifests content.
 
-After creating the bdpl resource on Kubernetes, i.e. via `kubectl apply`, the CF operator will start reconciliation, which will eventually result in the deployment
+After creating the `bdpl` resource on Kubernetes, i.e. via `kubectl apply`, the CF operator will start reconciliation, which will eventually result in the deployment
 of the BOSH release on Kubernetes.
 
 ## BDPL Component
@@ -68,9 +68,9 @@ This is the controller that manages the end user input(a BOSH manifest).
 
 Transform the concepts of BOSH into Kubernetes resources:
 
-- BOSH errands to ExtendedJobs CRD instances
-- BOSH instance_groups to ExtendedStatefulSet CRD instances
-- BOSH Variables to ExtendedSecrets CRD instance
+- BOSH `errands` to `ExtendedJob` CRD instances
+- BOSH `instance_groups` to `ExtendedStatefulSet` CRD instances
+- BOSH `variables` to `ExtendedSecret` CRD instance
 
 All of the three created *ExtendedJob* instances will eventually persist their STDOUT into new secrets under the same namespace.
 
@@ -103,7 +103,7 @@ The `secrets` resources,  generated by these `ExtendedSecrets` are referenced by
 ![bpm-controller-flow](quarks_bpm-controller_flow.png)
 *Fig. 4: The BPM controller*
 
-The BPM controller has the responsibility to generate Kubernetes resources per instance_group. It is triggered for each instance_group in the desired manifest, since we generate one BPM Secret for each. The reconciler starts each instance_group as its corresponding secret is created. It *does not wait* for all secrets to be ready.
+The BPM controller has the responsibility to generate Kubernetes resources per `instance_group`. It is triggered for each `instance_group` in the desired manifest, since we generate one BPM Secret for each. The reconciler starts each `instance_group` as its corresponding secret is created. It *does not wait* for all secrets to be ready.
 
 #### Watches in BPM controller
 
@@ -119,7 +119,7 @@ The BPM controller has the responsibility to generate Kubernetes resources per i
 
 #### Highlights in BPM controller
 
-The Secrets watched by the BPM Reconciler are [Versioned Secrets](extendedjob.md#versioned-secrets).
+The **Secrets** watched by the BPM Reconciler are [Versioned Secrets](extendedjob.md#versioned-secrets).
 
 Resources are _applied_ using an **upsert technique** [implementation](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/controller/controllerutil#CreateOrUpdate).
 
@@ -131,7 +131,7 @@ Persistent volumes are left behind.
 
 ## BDPL Abstract view
 
-Figure 5 is a diagram that explains the whole BOSHDeployment component controllers flow, in a more high level perspective.
+Figure 5 is a diagram that explains the whole `BOSHDeployment` component controllers flow, in a more high level perspective.
 
 ![deployment-state](https://docs.google.com/drawings/d/e/2PACX-1vTsCO5USd8AJIk_uHMRKl0NABuW85uVGJNebNvgI0Hz_9jhle6fcynLTcHh8cxW6lMgaV_DWyPEvm2-/pub?w=3161&h=2376)
 [edit](https://docs.google.com/drawings/d/126ExNqPxDg1LcB14pbtS5S-iJzLYPyXZ5Jr9vTfFqXA/edit?usp=sharing)

docs/controllers/extendedjob.md

@@ -38,7 +38,7 @@ Figure 1, illustrates the **ExtendedJob** component diagram and the set of contr
 ![errand-controller-flow](quarks_ejoberrandcontroller_flow.png)
 *Fig. 2: The Errand controller flow*
 
-This is the controller responsible for implementing Errands, this will lead to the generation of a Kubernetes job, in order to complete a task.
+This is the controller responsible for implementing **Errands**, this will lead to the generation of a Kubernetes job, in order to complete a task.
 
 #### Watches in Errand controller
 
@@ -58,7 +58,7 @@ This is the controller responsible for implementing Errands, this will lead to t
 - Errands are run manually by the user. They are created by setting `trigger.strategy: manual`.
 
 - After the `ExtendedJob` is created, run an errand by editing and applying the
-manifest, i.e. via `k edit errand1` and change `trigger.strategy: manual` to `trigger.strategy: now`. A `kubectl patch` is also a good way to trigger this type of `ExtendedJob`. After completion, this value is reset to `manual`.
+manifest, i.e. via `kubectl edit errand1` and change `trigger.strategy: manual` to `trigger.strategy: now`. A `kubectl patch` is also a good way to trigger this type of `ExtendedJob`. After completion, this value is reset to `manual`.
 
 ##### Auto-Errands
 
@@ -97,14 +97,11 @@ This is an auxiliary controller that relies on the Errand Controller output. It
 
 ##### Persisted Output
 
-- The developer can specify a `Secret` where the standard output/error output of
-the `ExtendedJob` is stored.
+- The developer can specify a `Secret` where the standard output/error output of the `ExtendedJob` is stored.
 
-- One secret is created or overwritten per container in the pod. The secrets'
-names are `<namePrefix>-<containerName>`.
+- One secret is created or overwritten per container in the pod. The secrets' names are `<namePrefix>-<containerName>`.
 
-- The only supported output type currently is json with a flat structure, i.e.
-all values being string values.
+- The only supported output type currently is JSON with a flat structure, i.e. all values being string values.
 
 - **Note:** Output of previous runs is overwritten.
 

docs/controllers/extendedsecret.md

@@ -34,7 +34,7 @@ Figure 1, illustrates the component and associated set of controllers.
 ![esec-controller-flow](quarks_eseccontroller_flow.png)
 *Fig. 2: The ExtendedSecret controller*
 
-The ExtendedSecret Controller will get a list of all variables referenced in a BOSH manifest with ops files applied, and will use this list of variables to generate the pertinent ExtendedSecret instances.
+The **ExtendedSecret** Controller will get a list of all variables referenced in a BOSH manifest with ops files applied, and will use this list of variables to generate the pertinent `ExtendedSecret` instances.
 
 #### Watches in esec controller
 
@@ -70,7 +70,7 @@ The developer can specify policies for rotation (e.g. automatic or not ) and how
 
 ##### Auto-approving Certificates
 
-A certificate `ExtendedSecret` can be signed by the Kube API Server. The ExtendedSecret Controller is responsible for generating the certificate signing request:
+A certificate `ExtendedSecret` can be signed by the Kube API Server. The **ExtendedSecret** Controller is responsible for generating the certificate signing request:
 
 ```yaml
 apiVersion: certificates.k8s.io/v1beta1
@@ -99,14 +99,14 @@ spec:
 
 #### Highlights in CSR controller
 
-The CertificateSigningRequest controller watches for `CertificateSigningRequest` and approves ExtendedSecret-owned CSRs and persists the generated certificate.
+The CertificateSigningRequest controller watches for `CertificateSigningRequest` and approves `ExtendedSecret`-owned CSRs and persists the generated certificate.
 
 ## Relationship with the BDPL component
 
 ![bdpl-ejob-relationship](quarks_gvc_and_esec_flow.png)
 *Fig. 4: Relationship between the Generated V.  controller and the ExtendedSecret component*
 
-Figure 4 illustrates the interaction of the **Generated Variables** Controller with the **ExtendedSecret** Controller. When reconciling, the Generated Variables Controller lists all variables of a BOSH manifest(basically all BOSH variables) and generates an ExtendedSecret instance per variable, which will trigger the ExtendedSecret controller.
+Figure 4 illustrates the interaction of the **Generated Variables** Controller with the **ExtendedSecret** Controller. When reconciling, the Generated Variables Controller lists all variables of a BOSH manifest(basically all BOSH variables) and generates an `ExtendedSecret` instance per variable, which will trigger the **ExtendedSecret** Controller.
 
 ## `ExtendedSecret` Examples
 

docs/controllers/extendedstatefulset.md

@@ -40,7 +40,7 @@ Figure 1 illustrates a **ExtendedStatefulset** component diagram that covers the
 ![ests-controller-flow](quarks_estscontroller_flow.png)
 *Fig. 2: The ExtendedStatefulset controller*
 
-This controller will generate a Kubernetes statefulset for each instance_group defined in the BOSH manifest. This Statefulset will also include a set of Kubernetes services, so that each component can be accessed on specific ports.
+This controller will generate a Kubernetes statefulset for each `instance_group` defined in the BOSH manifest. This `Statefulset` will also include a set of Kubernetes services, so that each component can be accessed on specific ports.
 
 #### Watches in sts controller
 
@@ -50,7 +50,7 @@ This controller will generate a Kubernetes statefulset for each instance_group d
 
 #### Reconciliation in sts controller
 
-Will generate versioned statefulsets with the required data to make all jobs of the instance_group runnable.
+Will generate versioned `Statefulsets` with the required data to make all jobs of the `instance_group` runnable.
 
 #### Scaling Restrictions (not implemented)
 
@@ -63,14 +63,14 @@ The operator watches all the `ConfigMaps` and `Secrets` referenced by the `State
 
 #### Exposing ExtendedStatefulSets Publicly
 
-Exposing extendedstatefulsets is similar to exposing statefulsets in kubernetes. A kubernetes service makes use of labels to select the pods which should be in the service. We need to use two labels to group the pods of a single instance group.
+Exposing `extendedstatefulsets` is similar to exposing `statefulsets` in kubernetes. A Kubernetes service makes use of labels to select the pods which should be in the service. We need to use two labels to group the pods of a single instance group.
 
-1. fissile.cloudfoundry.org/instance-group-name: ((instanceGroupName))
-2. fissile.cloudfoundry.org/deployment-name: ((deploymentName))
+1. `fissile.cloudfoundry.org/instance-group-name: ((instanceGroupName))`
+2. `fissile.cloudfoundry.org/deployment-name: ((deploymentName))`
 
 #### Cluster IP
 
-Following is the example which creates a service with type ClusterIp for a single instance group named nats in deployment nats-deployment for exposing port 4222.
+Following is the example which creates a service with type **ClusterIP** for a single instance group named `nats` in deployment `nats-deployment` for exposing port 4222.
 
 ```bash
 ---
@@ -91,17 +91,17 @@ spec:
 
 Complete example can be found [here](https://github.com/cloudfoundry-incubator/cf-operator/tree/master/docs/examples/bosh-deployment/boshdeployment-with-service.yaml).
 
-Though, by default, quarks creates three services of type ClusterIp as defined [here](https://github.com/cloudfoundry-incubator/cf-operator/blob/master/docs/from_bosh_to_kube.md#naming-conventions) for any instance group.
+Though, by default, quarks creates three services of type **ClusterIP** as defined [here](https://github.com/cloudfoundry-incubator/cf-operator/blob/master/docs/from_bosh_to_kube.md#naming-conventions) for any instance group.
 
 #### Load Balancer
 
-For creating a service type LoadBalancer, we just need to change the .spec.type to LoadBalancer in the above example. The LoadBalancer Ingress is your public ip specified in the output of this command `kubectl describe service nats-service`.
+For creating a service type **LoadBalancer**, we just need to change the `.spec.type` to `LoadBalancer` in the above example. The LoadBalancer Ingress is your public IP specified in the output of this command `kubectl describe service nats-service`.
 
 #### Ingress
 
-Ingress doesn't use any labels but just sits on top of services and acts as a smart router. You can create services of different types based on the above examples and use them as values in the ingress kubernetes spec. An example of Ingress can be found [here](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/#create-an-ingress-resource)
+**Ingress** doesn't use any labels but just sits on top of services and acts as a smart router. You can create services of different types based on the above examples and use them as values in the ingress Kubernetes spec. An example of Ingress can be found [here](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/#create-an-ingress-resource)
 
-For more information about kubernetes services, we recommend you to read [this](https://kubernetes.io/docs/concepts/services-networking/service/).
+For more information about Kubernetes services, we recommend you to read [this](https://kubernetes.io/docs/concepts/services-networking/service/).
 
 #### Extended Upgrade Support
 
@@ -200,7 +200,7 @@ If zones are set for an `ExtendedStatefulSet`, the following occurs:
   KUBE_AZ="zone name"
   BOSH_AZ="zone name"
   CF_OPERATOR_AZ="zone name"
-  AZ_INDEX=="zone index"
+  AZ_INDEX="zone index"
   ```
 
 #### Restarting on Config Change