This is an automated email from the ASF dual-hosted git repository.
joshfischer pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-heron.git
The following commit(s) were added to refs/heads/master by this push:
new b1e6519 [Heron 3707] ConfigMap Pod Template Support Documentation
(#3717)
b1e6519 is described below
commit b1e65199ca19c99355f7aae72164ba035411b588
Author: Saad Ur Rahman <[email protected]>
AuthorDate: Tue Nov 2 09:41:31 2021 -0400
[Heron 3707] ConfigMap Pod Template Support Documentation (#3717)
* [Docs] Initial document.
* [Docs] <ConfigMaps> section.
* [Docs] generating and registering a ConfigMap.
* [Docs] linking into the sidebar.
* [Docs] updated for the CONFIG-MAP-NAME.POD-TEMPLATE-NAME.
* [Docs] updates with output from <minkube kubectl> and for commands.
* [Docs] updates on how to disable and remove topologies in the event of an
error.
* [Docs] added items overwritten by Heron in Pod Templates.
* [Docs] minor typos and additions.
* [Docs] customisation of Heron's executor and support for auxiliary
containers.
* [Docs] fixed dangling references within the Scheduler and cleaned up the
State Manager in the event of a failed topology submission.
* [Docs] fixed description of Tolerations.
* [Docs] added info on Toleration merging.
* [Docs] updates for namespace and removal of deprecated taints.
* [Docs] Heron config values for Limits take precedence.
---
website2/docs/schedulers-k8s-pod-templates.md | 201 ++++++++++++++++++++++++++
website2/website/sidebars.json | 1 +
2 files changed, 202 insertions(+)
diff --git a/website2/docs/schedulers-k8s-pod-templates.md
b/website2/docs/schedulers-k8s-pod-templates.md
new file mode 100644
index 0000000..e6fe3c9
--- /dev/null
+++ b/website2/docs/schedulers-k8s-pod-templates.md
@@ -0,0 +1,201 @@
+---
+id: schedulers-k8s-pod-templates
+title: Kubernetes Pod Templates
+sidebar_label: Kubernetes Pod Templates
+---
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+> 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.
+
+<br/>
+
+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 most aspects of the Pods where the
computations occur, with some exceptions. There are some aspects of Pods for
which Heron will have the final say, and which will not be user-customizable.
Please view the tables at the end of this document to identify what is set by
Heron.
+
+<br>
+
+> ***System Administrators:***
+>
+> * You may wish to disable the ability to load custom Pod Templates. To
achieve this, you must pass the define option `-D
heron.kubernetes.pod.template.configmap.disabled=true` to the Heron API Server
on the command line during boot. This command has been added to the Kubernetes
configuration files to deploy the Heron API Server and is set to `false` by
default.
+> * If you have a custom `Role`/`ClusterRole` for the Heron API Server you
will need to ensure the `ServiceAccount` attached to the API server has the
correct permissions to access the `ConfigMaps`:
+>
+>```yaml
+>rules:
+>- apiGroups:
+> - ""
+> resources:
+> - configmaps
+> verbs:
+> - get
+> - watch
+> - list
+>```
+
+<br>
+
+## Preparation
+
+To deploy a custom Pod Template to 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:
+
+* `POD-TEMPLATE-NAME`: This is the name of the Pod Template's YAML definition
file. This is ***not*** a reserved variable and is a place-holder name.
+* `CONFIG-MAP-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 and is a place-holder name.
+* `heron.kubernetes.pod.template.configmap.name`: This variable name used as
the key passed to Heron for the `--config-property` on the CLI. This ***is*** a
reserved variable name.
+
+***NOTE***: Please do ***not*** use the `.` (period character) in the name of
the `CONFIG-MAP-NAME`. This character will be used as a delimiter when
submitting your topologies.
+
+It is highly advised that you validate your Pod Templates before placing them
in a `ConfigMap` to isolate any validity issues using a tool such as
[Kubeval](https://kubeval.instrumenta.dev/).
+
+### Pod Templates
+
+An example of a Pod Template is provided below, and is derived from the
configuration for the Heron Tracker Pod:
+
+```yaml
+apiVersion: v1
+kind: PodTemplate
+metadata:
+ name: heron-tracker
+ namespace: default
+template:
+ metadata:
+ labels:
+ app: heron-tracker
+ spec:
+ containers:
+ - name: heron-tracker
+ image: apache/heron:latest
+ ports:
+ - containerPort: 8888
+ name: api-port
+ resources:
+ requests:
+ cpu: "100m"
+ memory: "200M"
+ limits:
+ cpu: "400m"
+ memory: "512M"
+```
+
+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
+
+> You must place the `ConfigMap` in the same namespace as the Heron API Server
using the `--namespace` option in the commands below if the server is not in
the `default` namespace.
+
+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
+```
+
+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
+```
+
+The `ConfigMap` should appear similar to the one below for our example:
+
+```yaml
+apiVersion: v1
+data:
+ POD-TEMPLATE-NAME: |
+ apiVersion: v1
+ kind: PodTemplate
+ metadata:
+ name: heron-tracker
+ namespace: default
+ template:
+ metadata:
+ labels:
+ app: heron-tracker
+ spec:
+ containers:
+ - name: heron-tracker
+ image: apache/heron:latest
+ ports:
+ - containerPort: 8888
+ name: api-port
+ resources:
+ requests:
+ cpu: "100m"
+ memory: "200M"
+ limits:
+ cpu: "400m"
+ memory: "512M"
+kind: ConfigMap
+metadata:
+ creationTimestamp: "2021-09-27T21:55:30Z"
+ name: CONFIG-MAP-NAME
+ namespace: default
+ resourceVersion: "1313"
+ uid: ba001653-03d9-4ac8-804c-d2c55c974281
+```
+
+## Submitting
+
+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: `CONFIG-MAP-NAME.POD-TEMPLATE-NAME`
+
+Please note that you must concatenate `CONFIG-MAP-NAME` and
`POD-TEMPLATE-NAME` with a **`.`** (period chracter).
+
+For example:
+
+```bash
+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=CONFIG-MAP-NAME.POD-TEMPLATE-NAME
+```
+
+## Heron Configured Items in Pod Templates
+
+Heron will locate the container named `executor` in the Pod Template and
customize it as outlined below. All other containers within the Pod Template
will remain unchanged.
+
+### Executor Container
+
+All metadata for the `executor` container will be overwritten by Heron. In
some other cases, values from the Pod Template for the `executor` will be
overwritten by Heron as outline below.
+
+| Name | Description | Policy |
+|---|---|---|
+| `image` | The `executor` container's image. | Overwritten by Heron using
values form the config.
+| `env` | Environment variables are made available within the container. The
`HOST` and `POD_NAME` keys are required by Heron and are thus reserved. |
Merged with Heron's values taking precedence. Deduplication is based on `name`.
+| `ports` | Port numbers opened within the container. Some of these port
number are required by Heron and are thus reserved. The reserved ports are
defined in Heron's constants as [`6001`-`6010`]. | Merged with Heron's values
taking precedence. Deduplication is based on the `containerPort` value.
+| `limits` | Heron will attempt to load values for `cpu` and `memory` from
configs. If these values are not provided in the Configs, then values from the
Pod Templates will be used. | Heron's values take precedence over those in the
Pod Templates.
+| `volumeMounts` | These are the mount points within the `executor` container
for the `volumes` available in the Pod. | Merged with Heron's values taking
precedence. Deduplication is based on the `name` value.
+| Annotation: `prometheus.io/scrape` | Flag to indicate whether Prometheus
logs can be scraped and is set to `true`. | Value is overridden by Heron. |
+| Annotation `prometheus.io/port` | Port address for Prometheus log scraping
and is set to `8080`. | Values are overridden by Heron.
+| Annotation: Pod | Pod's revision/version hash. | Automatically set.
+| Annotation: Service | Labels services can use to attach to the Pod. |
Automatically set.
+| Label: `app` | Name of the application lauching the Pod and is set to
`Heron`. | Values are overridden by Heron.
+| Label: `topology`| The name of topology which was provided when submitting.
| User defined and supplied on the CLI.
+
+### Pod
+
+The following items will be set in the Pod Template's `spec` by Heron.
+
+| Name | Description | Policy |
+|---|---|---|
+`terminationGracePeriodSeconds` | Grace period to wait before shutting down
the Pod after a `SIGTERM` signal and is set to `0` seconds. | Values are
overridden by Heron.
+| `tolerations` | Attempts to schedule Pods with `taints` onto nodes hosting
Pods with matching `taints`. The entries below are included by default. <br>
Keys:<br>`node.kubernetes.io/not-ready` <br> `node.kubernetes.io/unreachable`
<br> Values (common):<br> `operator: Exists`<br> `effect: NoExecute`<br>
`tolerationSeconds: 10L` | Merged with Heron's values taking precedence.
Deduplication is based on the `key` value.
+| `containers` | Configurations for containers to be launched within the Pod.
| All `containers`, excluding the `executor`, are loaded as-is.
+| `volumes` | Volumes to be made available to the entire Pod. | Merged with
Heron's values taking precedence. Deduplication is based on the `name` value.
+| `secretVolumes` | Secrets to be mounted as volumes within the Pod. | Loaded
from the Heron configs if present.
diff --git a/website2/website/sidebars.json b/website2/website/sidebars.json
index 05de426..bab3043 100755
--- a/website2/website/sidebars.json
+++ b/website2/website/sidebars.json
@@ -53,6 +53,7 @@
"Schedulers": [
"schedulers-k8s-by-hand",
"schedulers-k8s-with-helm",
+ "schedulers-k8s-pod-templates",
"schedulers-aurora-cluster",
"schedulers-aurora-local",
"schedulers-local",
