Merge branch '3707-Pod-Template-Docs-dev' into 3707-Pod-Template-Supp…

…ort-Docs

website2/docs/schedulers-k8s-pod-templates.md

@@ -22,17 +22,19 @@ sidebar_label:  Kubernetes Pod Templates
 
 > This document demonstrates how you can utilize custom [Pod Templates](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates) embedded in [Configuration Maps](https://kubernetes.io/docs/concepts/configuration/configmap/) for your computation nodes - i.e., Spouts and Bolts. You may specify different Pod Templates for different topologies.
 
-When you deploy a topology to Heron on Kubernetes, you may specify a Pod Template to be used on the computation nodes. This can be achieved by providing a *unique* Pod Template name, and embedding the Pod Template within a Configuration Map. By default, Heron will use a default Pod Template which includes minimal configurations.
+When you deploy a topology to Heron on Kubernetes, you may specify a Pod Template to be used on the computation nodes. This can be achieved by providing a valid Pod Template, and embedding the Pod Template within a Configuration Map. By default, Heron will use a minimally configured Pod Template which is adequate to deploy a topology.
 
 Pod Templates will allow you to configure all aspects of the Pods where the computations occur. For instance, it might be desirable to set tighter security parameters in case of sensitive topologies or configure the metadata for the Pods to facilitate easier monitoring in `kubectl`. The use cases are boundless.
 
 ## Preparation
 
-To deploy a custom Pod Template to the Kubernetes with your topology, you must provide a valid Pod Template embedded in a valid Configuration Map. The name of the Pod Template *must be unique*, if not the first match for the specified Pod Template will be utilized.
+To deploy a custom Pod Template to the Kubernetes with your topology, you must provide a valid Pod Template embedded in a valid Configuration Map. We will be using the following variables throughout this document, some of which are reserved variable names:
 
-It is highly advised that you validate your Pod Templates before placing them in a `ConfigMap` to isolate any validity issues.
+* `POD-TEMPLATE-NAME`: This is the name of the Pod Template's YAML definition file. This is ***not*** a reserved variable name.
+* `CONFIGMAP-NAME`: This is the name which will be used by the Configuration Map in which the Pod Template will be embedded by `kubectl`. This is ***not*** a reserved variable name.
+* `heron.kubernetes.pod.template.configmap.name`: Variable name used as the key passed to `kubectl` on the CLI. This ***is*** a reserved variable name.
 
-We will be using `POD-TEMPLATE-NAME` to refer to the name of key item in the `ConfigMap` and `CONFIGMAP-NAME` to refer to the name of the `ConfigMap`.
+It is highly advised that you validate your Pod Templates before placing them in a `ConfigMap` to isolate any validity issues.
 
 ### Pod Templates
 
@@ -64,17 +66,17 @@ template:
             memory: "512M"
 ```
 
-You would need to save this file as `POD-TEMPLATE-NAME.yaml`. Once you have a valid Pod Template you may proceed to generate a `ConfigMap`.
+You would need to save this file as `POD-TEMPLATE-NAME`. Once you have a valid Pod Template you may proceed to generate a `ConfigMap`.
 
 ### Configuration Maps
 
-TO generate a `ConfigMap` you will need to run the following command:
+To generate a `ConfigMap` you will need to run the following command:
 
 ```bash
 kubectl create configmap CONFIG-MAP-NAME --from-file=path/to/POD-TEMPLATE-NAME.yaml
 ```
 
-If you then run the following command:
+You may then want to verify the contents of the `ConfigMap` by running the following command:
 
 ```bash
 kubectl get configmaps CONFIG-MAP-NAME -o yaml
@@ -121,10 +123,12 @@ data:
 
 ## Submitting
 
-To use the `ConfigMap` for a topology you would submit with the additional flag `--confg-property`. The `--config-property` take a key value pair:
+To use the `ConfigMap` for a topology you would submit with the additional flag `--confg-property`. The `--config-property key=value` takes a key value pair:
 
 * Key: `heron.kubernetes.pod.template.configmap.name`
-* Value: `POD-TEMPLATE-NAME`
+* Value: `CONFIGMAP-NAME.POD-TEMPLATE-NAME`
+
+Please note that you must concatenate `CONFIGMAP-NAME` and `POD-TEMPLATE-NAME` with a **`.`** (period chracter).
 
 For example:
 
@@ -133,5 +137,5 @@ heron submit kubernetes \
   --service-url=http://localhost:8001/api/v1/namespaces/default/services/heron-apiserver:9000/proxy \
   ~/.heron/examples/heron-api-examples.jar \
   org.apache.heron.examples.api.AckingTopology acking \
-  --config-property heron.kubernetes.pod.template.configmap.name=POD-TEMPLATE-NAME
+  --config-property heron.kubernetes.pod.template.configmap.name=CONFIGMAP-NAME.POD-TEMPLATE-NAME
 ```