From de752b0fb11a90014a60b8b025f5df2d9a00fe9a Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 12:23:57 +0800 Subject: [PATCH 01/37] style: trim whitespaces before `{{include}}` --- templates/_configmap.yaml | 2 +- templates/_cronjob.yaml | 6 +++--- templates/_deployment.yaml | 6 +++--- templates/_hpa.yaml | 2 +- templates/_ingress.yaml | 2 +- templates/_metadata.tpl | 4 ++-- templates/_pdb.yaml | 2 +- templates/_secret.yaml | 2 +- templates/_service.yaml | 2 +- templates/_serviceaccount.yaml | 2 +- templates/_servicemonitor.yaml | 2 +- 11 files changed, 16 insertions(+), 16 deletions(-) diff --git a/templates/_configmap.yaml b/templates/_configmap.yaml index d509ada..c583a83 100644 --- a/templates/_configmap.yaml +++ b/templates/_configmap.yaml @@ -5,7 +5,7 @@ apiVersion: v1 kind: ConfigMap metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} data: {} {{- end -}} diff --git a/templates/_cronjob.yaml b/templates/_cronjob.yaml index 4dc54a0..6aec3a1 100644 --- a/templates/_cronjob.yaml +++ b/templates/_cronjob.yaml @@ -12,7 +12,7 @@ spec: apiVersion: batch/v1beta1 kind: CronJob metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} spec: schedule: "{{ $cronJob.schedule }}" {{- with $cronJob.concurrencyPolicy }} @@ -27,10 +27,10 @@ spec: jobTemplate: metadata: labels: - {{ include "common.selectorLabels" $top | nindent 8 }} + {{- include "common.selectorLabels" $top | nindent 8 }} spec: template: - {{ include "common.pod.template" (list $top $pod "common.cronJob.pod") | nindent 8 }} + {{- include "common.pod.template" (list $top $pod "common.cronJob.pod") | nindent 8 }} {{- end -}} {{- define "common.cronJob" -}} diff --git a/templates/_deployment.yaml b/templates/_deployment.yaml index fcec8fc..0f6e9ae 100644 --- a/templates/_deployment.yaml +++ b/templates/_deployment.yaml @@ -7,16 +7,16 @@ apiVersion: apps/v1 kind: Deployment metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} spec: {{- if not $autoscaling.enabled }} replicas: {{ $deployment.replicaCount | default 1 }} {{- end }} selector: matchLabels: - {{ include "common.selectorLabels" $top | nindent 6 }} + {{- include "common.selectorLabels" $top | nindent 6 }} template: - {{ include "common.pod.template" . | nindent 4 }} + {{- include "common.pod.template" . | nindent 4 }} {{- end -}} {{- define "common.deployment" -}} diff --git a/templates/_hpa.yaml b/templates/_hpa.yaml index 4253f6b..c135600 100644 --- a/templates/_hpa.yaml +++ b/templates/_hpa.yaml @@ -6,7 +6,7 @@ apiVersion: autoscaling/v2beta2 kind: HorizontalPodAutoscaler metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} spec: scaleTargetRef: apiVersion: apps/v1 diff --git a/templates/_ingress.yaml b/templates/_ingress.yaml index 731b60a..8f4f0e6 100644 --- a/templates/_ingress.yaml +++ b/templates/_ingress.yaml @@ -21,7 +21,7 @@ apiVersion: extensions/v1beta1 {{- end }} kind: Ingress metadata: - {{ include "common.metadata" (append . "common.ingress.metadata") | nindent 2 }} + {{- include "common.metadata" (append . "common.ingress.metadata") | nindent 2 }} spec: {{- if $ingress.tls }} tls: diff --git a/templates/_metadata.tpl b/templates/_metadata.tpl index 3efe2e8..23f3506 100644 --- a/templates/_metadata.tpl +++ b/templates/_metadata.tpl @@ -20,7 +20,7 @@ app.kubernetes.io/name: {{ include "common.name" . }} app.kubernetes.io/instance: {{ .Release.Name }} {{- end -}} -{{ define "common.metadata.tpl" -}} +{{- define "common.metadata.tpl" -}} {{- $top := first . -}} name: {{ include "common.fullname" $top }} labels: @@ -30,6 +30,6 @@ labels: {{- /* Create a standard metadata header */ -}} -{{ define "common.metadata" -}} +{{- define "common.metadata" -}} {{- include "common.utils.merge" (append . "common.metadata.tpl") -}} {{- end -}} diff --git a/templates/_pdb.yaml b/templates/_pdb.yaml index ee88c8f..7a65732 100644 --- a/templates/_pdb.yaml +++ b/templates/_pdb.yaml @@ -6,7 +6,7 @@ apiVersion: policy/v1beta1 kind: PodDisruptionBudget metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} spec: selector: matchLabels: diff --git a/templates/_secret.yaml b/templates/_secret.yaml index 0bcbc66..46fcfdd 100644 --- a/templates/_secret.yaml +++ b/templates/_secret.yaml @@ -5,7 +5,7 @@ apiVersion: v1 kind: Secret metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} type: Opaque data: {} {{- end -}} diff --git a/templates/_service.yaml b/templates/_service.yaml index 3f151b8..6ac2548 100644 --- a/templates/_service.yaml +++ b/templates/_service.yaml @@ -6,7 +6,7 @@ apiVersion: v1 kind: Service metadata: - {{ include "common.metadata" (list $top) | nindent 2 }} + {{- include "common.metadata" (list $top) | nindent 2 }} spec: type: {{ $service.type }} ports: diff --git a/templates/_serviceaccount.yaml b/templates/_serviceaccount.yaml index bd425f0..82b79ab 100644 --- a/templates/_serviceaccount.yaml +++ b/templates/_serviceaccount.yaml @@ -14,7 +14,7 @@ annotations: apiVersion: v1 kind: ServiceAccount metadata: - {{ include "common.metadata" (append . "common.serviceAccount.metadata") | nindent 2 }} + {{- include "common.metadata" (append . "common.serviceAccount.metadata") | nindent 2 }} {{- end -}} {{- define "common.serviceAccount" -}} diff --git a/templates/_servicemonitor.yaml b/templates/_servicemonitor.yaml index 965a17b..21815a1 100644 --- a/templates/_servicemonitor.yaml +++ b/templates/_servicemonitor.yaml @@ -13,7 +13,7 @@ namespace: {{ . }} apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: - {{ include "common.metadata" (append . "common.serviceMonitor.metadata") | nindent 2 }} + {{- include "common.metadata" (append . "common.serviceMonitor.metadata") | nindent 2 }} spec: selector: matchLabels: From 18cadb5759593f2c15e8abea429e21d1480d38c8 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 12:51:04 +0800 Subject: [PATCH 02/37] refactor: correct variable name `$pod` => `$deployment` --- templates/_pdb.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/_pdb.yaml b/templates/_pdb.yaml index 7a65732..c163abf 100644 --- a/templates/_pdb.yaml +++ b/templates/_pdb.yaml @@ -24,9 +24,9 @@ spec: {{- define "common.pdb" -}} {{- $top := first . -}} -{{- $pod := index . 2 -}} +{{- $deployment := index . 2 -}} {{- $autoscaling := index . 3 -}} -{{- if or (and $autoscaling.enabled (gt ($autoscaling.minReplicas | int) 1)) (gt ($pod.replicaCount | int) 1) }} +{{- if or (and $autoscaling.enabled (gt ($autoscaling.minReplicas | int) 1)) (gt ($deployment.replicaCount | int) 1) }} {{- include "common.utils.merge" (append . "common.pdb.tpl") -}} {{- end -}} {{- end -}} From 7298936b6de0d76401d02f4bb1ab473fd887a747 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 15:19:41 +0800 Subject: [PATCH 03/37] docs: copy and update README from the original repo --- README.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d2a3b0c..45f2346 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,43 @@ # Common: The Helm Helper Chart -This chart is designed to make it easier for you to build and maintain Helm charts. +This chart was originally forked from [`incubator/common`](https://github.com/helm/charts/tree/master/incubator/common), which is designed to make it easier for you to build and maintain Helm charts. It provides utilities that reflect best practices of Kubernetes chart development, making it faster for you to write charts. + + + +## Resource Kinds + +Kubernetes defines a variety of resource kinds, from `Secret` to `StatefulSet`. We define some of the most common kinds in a way that lets you easily work with them. + +The resource kind templates are designed to make it much faster for you to define _basic_ versions of these resources. They allow you to extend and modify just what you need, without having to copy around lots of boilerplate. + +To make use of these templates you must define a template that will extend the base template (though it can be empty). The name of this template is then passed to the base template, for example: + +```yaml +{{- template "common.service" (list . .Values.service "mychart.service") -}} +{{- define "mychart.service" -}} +## Define overrides for your Service resource here, e.g. +# metadata: +# labels: +# custom: label +# spec: +# ports: +# - port: 8080 +# targetPort: http +# protocol: TCP +# name: http +{{- end -}} +``` + +Note that the `common.service` template defines three parameters: + +- The root context (usually `.`) +- A dictionary of values which are used in the template +- A optional template name containing the service definition overrides + +A limitation of the Go template library is that a template can only take a single argument. The `list` function is used to workaround this by constructing a list or array of arguments that is passed to the template. + +The `common.service` template is responsible for rendering the templates with the root context and merging any overrides. As you can see, this makes it very easy to create a basic `Service` resource without having to copy around the standard metadata and labels. + +Each implemented base resource is described in greater detail below. \ No newline at end of file From 6eb1ca375f7be5fe86926b6110d1394d12fc24f7 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 15:33:50 +0800 Subject: [PATCH 04/37] docs: add description about `common.service` --- README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 115 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 45f2346..2796415 100644 --- a/README.md +++ b/README.md @@ -40,4 +40,118 @@ A limitation of the Go template library is that a template can only take a singl The `common.service` template is responsible for rendering the templates with the root context and merging any overrides. As you can see, this makes it very easy to create a basic `Service` resource without having to copy around the standard metadata and labels. -Each implemented base resource is described in greater detail below. \ No newline at end of file +Each implemented base resource is described in greater detail below. + + + +### `common.service` + +The `common.service` template accepts a list of three values: + +- the top context +- `$service`, a dictionary of values used in the service template +- [optional] the template name of the overrides + +It creates a basic `Service` resource with the following defaults: + +- Service type (ClusterIP, NodePort, LoadBalancer) made configurable by `$service.type` +- Named port `http` configured on port `$service.port` +- Selector set to + + ```yaml + app.kubernetes.io/name: {{ template "common.name" }} + app.kubernetes.io/instance: {{ .Release.Name }} + ``` + + to match the default used in the `Deployment` resource + +Example template: + +```yaml +{{- template "common.service" (list . .Values.service "mychart.mail.service") -}} +{{- define "mychart.mail.service" -}} +{{- $top := first . -}} +metadata: + name: {{ template "common.fullname" $top }}-mail # overrides the default name to add a suffix + labels: # appended to the labels section + protocol: mail +spec: + ports: # composes the `ports` section of the service definition. + - name: smtp + port: 25 + targetPort: 25 + - name: imaps + port: 993 + targetPort: 993 + selector: # this is appended to the default selector + protocol: mail +{{- end }} +--- +{{ template "common.service" (list . .Values.service "mychart.web.service") -}} +{{- define "mychart.web.service" -}} +{{- $top := first . -}} +metadata: + name: {{ template "common.fullname" $top }}-www # overrides the default name to add a suffix + labels: # appended to the labels section + protocol: www +spec: + ports: # composes the `ports` section of the service definition. + - name: www + port: 80 + targetPort: 8080 +{{- end -}} +``` + +The above template defines _two_ services: a web service and a mail service. + +The most important part of a service definition is the `ports` object, which defines the ports that this service will listen on. Most of the time, `selector` is computed for you. But you can replace it or add to it. + +The output of the example above is: + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + protocol: www + name: release-name-mychart-www +spec: + ports: + - name: www + port: 80 + targetPort: 8080 + selector: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart + type: ClusterIP +--- +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + protocol: mail + name: release-name-mychart-mail +spec: + ports: + - name: smtp + port: 25 + targetPort: 25 + - name: imaps + port: 993 + targetPort: 993 + selector: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart + protocol: mail + type: ClusterIP +``` From e75a173d9df4e4fba56197173fbe7e5a572b8f62 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 16:34:27 +0800 Subject: [PATCH 05/37] docs: add description about `common.deployment` --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 2796415..2419b13 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,51 @@ Each implemented base resource is described in greater detail below. +### `common.deployment` + +The `common.deployment` template accepts a list of three values: + +- the top context +- `$deployment`, a dictionary of values used in the deployment template +- `$autoscaling`, a dictionary of values used in the hpa template +- [optional] the template name of the overrides + +It defines a basic `Deployment` with the following settings: + +| Value | Description | +| ----- | ----------- | +| `$deployment.replicaCount` | Number of replica. If autoscaling enabled, this field will be ignored | +| `$deployment.imagePullSecrets` | [optional] Name of Secret resource containing private registry credentials | +| `$deployment.podSecurityContext` | [optional] Security options for pod | +| `$deployment.nodeSelector` | [optional] Node labels for pod assignment | +| `$deployment.affinity` | [optional] Expressions for affinity | +| `$deployment.tolerations` | [optional] Toleration labels for pod assignment | +| `$autoscaling.enabled` | [optional] Set this to `true` to enable autoscaling | + +Underneath the hood, it uses [`common.container`](#commoncontainer). + +By default, the pod template within the deployment defines the labels + +```yaml +app.kubernetes.io/name: {{ template "common.name" }} +app.kubernetes.io/instance: {{ .Release.Name }} +``` + +as this is also used as the selector. The standard set of labels are not used as some of these can change during upgrades, which causes the replica sets and pods to not correctly match. + +Example use: + +```yaml +{{- template "common.deployment" (list . .Values .Values.autoscaling) -}} + +## The following is the same as above: +# {{- template "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} +# {{- define "mychart.deployment" -}} +# {{- end -}} +``` + + + ### `common.service` The `common.service` template accepts a list of three values: From 9a5a128c6e07ecd9e9c4f2d061891366086de49d Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 17:19:05 +0800 Subject: [PATCH 06/37] refactor: correct indents --- templates/_container.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/_container.yaml b/templates/_container.yaml index a012156..3a6c310 100644 --- a/templates/_container.yaml +++ b/templates/_container.yaml @@ -6,11 +6,11 @@ {{- $image := $container.image | default (dict) -}} name: {{ $top.Chart.Name }} securityContext: - {{- toYaml $container.securityContext | nindent 4 }} + {{- toYaml $container.securityContext | nindent 2 }} image: "{{ $image.repository }}:{{ $image.tag | default $top.Chart.AppVersion }}" imagePullPolicy: {{ $container.image.pullPolicy }} resources: - {{- toYaml $container.resources | nindent 4 }} + {{- toYaml $container.resources | nindent 2 }} {{- end -}} {{- define "common.container" -}} From 5e84d4fb5f281f8232fe55e0cfd0c47b8a529969 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 17:19:41 +0800 Subject: [PATCH 07/37] refactor: `$values` => `$pod` --- templates/_pod.tpl | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/templates/_pod.tpl b/templates/_pod.tpl index 9f9c555..76fa0b2 100644 --- a/templates/_pod.tpl +++ b/templates/_pod.tpl @@ -2,29 +2,29 @@ {{- define "common.pod.template.tpl" -}} {{- $top := first . -}} -{{- $values := index . 1 -}} +{{- $pod := index . 1 -}} metadata: labels: {{- include "common.selectorLabels" $top | nindent 4 }} spec: - {{- with $values.imagePullSecrets }} + {{- with $pod.imagePullSecrets }} imagePullSecrets: {{- toYaml . | nindent 8 }} {{- end }} serviceAccountName: {{ include "common.serviceAccountName" $top }} securityContext: - {{- toYaml $values.podSecurityContext | nindent 4 }} + {{- toYaml $pod.podSecurityContext | nindent 4 }} containers: - {{- include "common.container" . | nindent 6 }} - {{- with $values.nodeSelector }} + {{- with $pod.nodeSelector }} nodeSelector: {{- toYaml . | nindent 4 }} {{- end }} - {{- with $values.affinity }} + {{- with $pod.affinity }} affinity: {{- toYaml . | nindent 4 }} {{- end }} - {{- with $values.tolerations }} + {{- with $pod.tolerations }} tolerations: {{- toYaml . | nindent 4 }} {{- end }} From 2729adff4388f3b9136d20cf00d5fc8711400c7f Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Wed, 22 Apr 2020 17:20:10 +0800 Subject: [PATCH 08/37] docs: add description about `common.container` --- README.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 142 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2419b13..cf9d1aa 100644 --- a/README.md +++ b/README.md @@ -102,12 +102,10 @@ It creates a basic `Service` resource with the following defaults: - Service type (ClusterIP, NodePort, LoadBalancer) made configurable by `$service.type` - Named port `http` configured on port `$service.port` - Selector set to - ```yaml app.kubernetes.io/name: {{ template "common.name" }} app.kubernetes.io/instance: {{ .Release.Name }} ``` - to match the default used in the `Deployment` resource Example template: @@ -200,3 +198,145 @@ spec: protocol: mail type: ClusterIP ``` + + + +## Partial Objects + +When writing Kubernetes resources, you may find the following helpers useful to construct parts of the spec. + + + +### `common.container` + +The `common.container` template accepts a list of three values: + +- the top context +- `$container`, a dictionary of values used in the container template +- [optional] the template name of the overrides + +It creates a basic `Container` spec to be used within a `Deployment` or `CronJob`. It holds the following defaults: + +- The name is set to the chart name +- Uses `$container.image` to describe the image to run, with the following spec: + ```yaml + image: + repository: nginx + tag: stable + pullPolicy: IfNotPresent + ``` +- Lays out the security options using `$container.securityContext` +- Lays out the compute resources using `$container.resources` + +Example use: + +```yaml +{{- template "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} +{{- define "mychart.deployment" -}} +## Define overrides for your Deployment resource here, e.g. +spec: + template: + spec: + containers: + - {{- include "common.container" (append . "mychart.deployment.container") | nindent 10 }} +{{- end -}} +{{- define "mychart.deployment.container" -}} +## Define overrides for your Container here, e.g. +ports: + - name: http + containerPort: 80 + protocol: TCP +livenessProbe: + httpGet: + path: / + port: http +readinessProbe: + httpGet: + path: / + port: http +{{- end -}} +``` + +The above example creates a `Deployment` resource which makes use of the `common.container` template to populate the PodSpec's container list. The usage of this template is similar to the other resources, you must define and reference a template that contains overrides for the container object. + +The most important part of a container definition is the image you want to run. As mentioned above, this is derived from `$container.image` by default. It is a best practice to define the image, tag and pull policy in your charts' values as this makes it easy for an operator to change the image registry, or use a specific tag or version. Another example of configuration that should be exposed to chart operators is the container's required compute resources, as this is also very specific to an operators environment. An example `values.yaml` for your chart could look like: + +```yaml +replicaCount: 1 +image: + repository: nginx + tag: stable + pullPolicy: IfNotPresent +securityContext: + capabilities: + drop: + - ALL + readOnlyRootFilesystem: true + runAsNonRoot: true + runAsUser: 1000 +resources: + limits: + cpu: 100m + memory: 128Mi + requests: + cpu: 100m + memory: 128Mi +``` + +The output of running the above values through the earlier template is: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +spec: + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart + template: + metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart + spec: + containers: + - image: nginx:stable + imagePullPolicy: IfNotPresent + livenessProbe: + httpGet: + path: / + port: http + name: mychart + ports: + - containerPort: 80 + name: http + protocol: TCP + readinessProbe: + httpGet: + path: / + port: http + resources: + limits: + cpu: 100m + memory: 128Mi + requests: + cpu: 100m + memory: 128Mi + securityContext: + capabilities: + drop: + - ALL + readOnlyRootFilesystem: true + runAsNonRoot: true + runAsUser: 1000 + serviceAccountName: release-name-mychart +``` From 75e6d18687b4dc3f05bbe747ee29861ec4dabf90 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:15:29 +0800 Subject: [PATCH 09/37] docs: replace `{{ template }}` with `{{ include }}` --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index cf9d1aa..8423738 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ The resource kind templates are designed to make it much faster for you to defin To make use of these templates you must define a template that will extend the base template (though it can be empty). The name of this template is then passed to the base template, for example: ```yaml -{{- template "common.service" (list . .Values.service "mychart.service") -}} +{{- include "common.service" (list . .Values.service "mychart.service") -}} {{- define "mychart.service" -}} ## Define overrides for your Service resource here, e.g. # metadata: @@ -70,7 +70,7 @@ Underneath the hood, it uses [`common.container`](#commoncontainer). By default, the pod template within the deployment defines the labels ```yaml -app.kubernetes.io/name: {{ template "common.name" }} +app.kubernetes.io/name: {{ include "common.name" }} app.kubernetes.io/instance: {{ .Release.Name }} ``` @@ -79,10 +79,10 @@ as this is also used as the selector. The standard set of labels are not used as Example use: ```yaml -{{- template "common.deployment" (list . .Values .Values.autoscaling) -}} +{{- include "common.deployment" (list . .Values .Values.autoscaling) -}} ## The following is the same as above: -# {{- template "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} +# {{- include "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} # {{- define "mychart.deployment" -}} # {{- end -}} ``` @@ -103,7 +103,7 @@ It creates a basic `Service` resource with the following defaults: - Named port `http` configured on port `$service.port` - Selector set to ```yaml - app.kubernetes.io/name: {{ template "common.name" }} + app.kubernetes.io/name: {{ include "common.name" }} app.kubernetes.io/instance: {{ .Release.Name }} ``` to match the default used in the `Deployment` resource @@ -111,11 +111,11 @@ It creates a basic `Service` resource with the following defaults: Example template: ```yaml -{{- template "common.service" (list . .Values.service "mychart.mail.service") -}} +{{- include "common.service" (list . .Values.service "mychart.mail.service") -}} {{- define "mychart.mail.service" -}} {{- $top := first . -}} metadata: - name: {{ template "common.fullname" $top }}-mail # overrides the default name to add a suffix + name: {{ include "common.fullname" $top }}-mail # overrides the default name to add a suffix labels: # appended to the labels section protocol: mail spec: @@ -130,11 +130,11 @@ spec: protocol: mail {{- end }} --- -{{ template "common.service" (list . .Values.service "mychart.web.service") -}} +{{ include "common.service" (list . .Values.service "mychart.web.service") -}} {{- define "mychart.web.service" -}} {{- $top := first . -}} metadata: - name: {{ template "common.fullname" $top }}-www # overrides the default name to add a suffix + name: {{ include "common.fullname" $top }}-www # overrides the default name to add a suffix labels: # appended to the labels section protocol: www spec: @@ -231,7 +231,7 @@ It creates a basic `Container` spec to be used within a `Deployment` or `CronJob Example use: ```yaml -{{- template "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} +{{- include "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} {{- define "mychart.deployment" -}} ## Define overrides for your Deployment resource here, e.g. spec: From 7bbf578ee562e8629020dbde86c929998f572ce9 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:21:29 +0800 Subject: [PATCH 10/37] docs: correct indentations --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8423738..1bf9bd6 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ To make use of these templates you must define a template that will extend the b # custom: label # spec: # ports: -# - port: 8080 -# targetPort: http -# protocol: TCP -# name: http +# - port: 8080 +# targetPort: http +# protocol: TCP +# name: http {{- end -}} ``` @@ -238,14 +238,14 @@ spec: template: spec: containers: - - {{- include "common.container" (append . "mychart.deployment.container") | nindent 10 }} + - {{- include "common.container" (append . "mychart.deployment.container") | nindent 8 }} {{- end -}} {{- define "mychart.deployment.container" -}} ## Define overrides for your Container here, e.g. ports: - - name: http - containerPort: 80 - protocol: TCP +- name: http + containerPort: 80 + protocol: TCP livenessProbe: httpGet: path: / @@ -270,7 +270,7 @@ image: securityContext: capabilities: drop: - - ALL + - ALL readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 1000 From 619f27ace120424aed84f45eb1f4abc04bca596d Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:26:01 +0800 Subject: [PATCH 11/37] docs: add `Contents` section --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 1bf9bd6..f4144db 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,16 @@ It provides utilities that reflect best practices of Kubernetes chart developmen +## Contents + +- [Resource Kinds](#resource-kinds) + * [`common.deployment`](#commondeployment) + * [`common.service`](#commonservice) +- [Partial Objects](#partial-objects) + * [`common.container`](#commoncontainer) + + + ## Resource Kinds Kubernetes defines a variety of resource kinds, from `Secret` to `StatefulSet`. We define some of the most common kinds in a way that lets you easily work with them. From 98902aafdb770029e3ee52b7594b3dcb33eefba0 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:36:51 +0800 Subject: [PATCH 12/37] docs: add description about `common.configMap` --- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f4144db..06b4ee8 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen ## Contents - [Resource Kinds](#resource-kinds) + * [`common.configMap`](#commonconfigmap) * [`common.deployment`](#commondeployment) * [`common.service`](#commonservice) - [Partial Objects](#partial-objects) @@ -54,9 +55,54 @@ Each implemented base resource is described in greater detail below. +### `common.configMap` + +The `common.configMap` template accepts a list of two values: + +- the top context +- [optional] the template name of the overrides + +It creates an empty `ConfigMap` resource that you can override with your configuration. + +Example use: + +```yaml +{{- include "common.configMap" (list . "mychart.configMap") -}} +{{- define "mychart.configMap" -}} +data: + zeus: cat + athena: cat + julius: cat + one: |- + {{ .Files.Get "file1.txt" }} +{{- end -}} +``` + +Output: + +```yaml +apiVersion: v1 +data: + athena: cat + julius: cat + one: This is a file. + zeus: cat +kind: ConfigMap +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +``` + + + ### `common.deployment` -The `common.deployment` template accepts a list of three values: +The `common.deployment` template accepts a list of four values: - the top context - `$deployment`, a dictionary of values used in the deployment template From f848f3e7f4ae333fef6821fa2483ac358d4d5af7 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:42:15 +0800 Subject: [PATCH 13/37] docs: add description about `common.secret` --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/README.md b/README.md index 06b4ee8..c569b51 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen - [Resource Kinds](#resource-kinds) * [`common.configMap`](#commonconfigmap) * [`common.deployment`](#commondeployment) + * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) @@ -144,6 +145,51 @@ Example use: ``` +### `common.secret` + +The `common.secret` template accepts a list of two values: + +- the top context +- [optional] the template name of the overrides + +It creates an empty `Secret` resource that you can override with your secrets. + +Example use: + +```yaml +{{- include "common.secret" (list . "mychart.secret") -}} +{{- define "mychart.secret" -}} +data: + zeus: {{ print "cat" | b64enc }} + athena: {{ print "cat" | b64enc }} + julius: {{ print "cat" | b64enc }} + one: |- + {{ .Files.Get "file1.txt" | b64enc }} +{{- end -}} +``` + +Output: + +```yaml +apiVersion: v1 +data: + athena: Y2F0 + julius: Y2F0 + one: VGhpcyBpcyBhIGZpbGUuCg== + zeus: Y2F0 +kind: Secret +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +type: Opaque +``` + + ### `common.service` From 5fcc2735e2e26d182b0b0b20044a341e7bd28bdd Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 09:56:57 +0800 Subject: [PATCH 14/37] docs: add description about `common.ingress` --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/README.md b/README.md index c569b51..2ad5bec 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen - [Resource Kinds](#resource-kinds) * [`common.configMap`](#commonconfigmap) * [`common.deployment`](#commondeployment) + * [`common.ingress`](#commoningress) * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) - [Partial Objects](#partial-objects) @@ -145,6 +146,81 @@ Example use: ``` + +### `common.ingress` + +The `common.ingress` template accepts a list of four values: + +- the top context +- `$ingress`, a dictionary of values used in the ingress template +- `$service`, a dictionary of values used in the service template +- [optional] the template name of the overrides + +It is designed to give you a well-defined `Ingress` resource, that can be configured using `$ingress`. An example values file that can be used to configure the `Ingress` resource is: + +```yaml +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + kubernetes.io/tls-acme: "true" + hosts: + - host: chart-example.local + paths: + - /path/to/somewhere + tls: + - secretName: chart-example-tls + hosts: + - chart-example.local +service: + type: ClusterIP + port: 80 +``` + +Example use: + +```yaml +{{- include "common.ingress" (list . .Values.ingress .Values.service) -}} + +## The following is the same as above: +# {{- include "common.ingress" (list . .Values.ingress .Values.service "mychart.ingress") -}} +# {{- define "mychart.ingress" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: networking.k8s.io/v1beta1 +kind: Ingress +metadata: + annotations: + kubernetes.io/ingress.class: nginx + kubernetes.io/tls-acme: "true" + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +spec: + rules: + - host: "chart-example.local" + http: + paths: + - backend: + serviceName: release-name-mychart + servicePort: 80 + path: /path/to/somewhere + tls: + - hosts: + - "chart-example.local" + secretName: chart-example-tls +``` + + + ### `common.secret` The `common.secret` template accepts a list of two values: From 24345547823a28ceace8f70b923a26c73775cd55 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 11:33:24 +0800 Subject: [PATCH 15/37] docs: add description about `common.pod.template` --- README.md | 75 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 2ad5bec..e33b811 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ To make use of these templates you must define a template that will extend the b {{- end -}} ``` -Note that the `common.service` template defines three parameters: +Note that the [`common.service`](#commonservice) template defines three parameters: - The root context (usually `.`) - A dictionary of values which are used in the template @@ -51,7 +51,7 @@ Note that the `common.service` template defines three parameters: A limitation of the Go template library is that a template can only take a single argument. The `list` function is used to workaround this by constructing a list or array of arguments that is passed to the template. -The `common.service` template is responsible for rendering the templates with the root context and merging any overrides. As you can see, this makes it very easy to create a basic `Service` resource without having to copy around the standard metadata and labels. +The [`common.service`](#commonservice) template is responsible for rendering the templates with the root context and merging any overrides. As you can see, this makes it very easy to create a basic `Service` resource without having to copy around the standard metadata and labels. Each implemented base resource is described in greater detail below. @@ -61,7 +61,7 @@ Each implemented base resource is described in greater detail below. The `common.configMap` template accepts a list of two values: -- the top context +- `$top`, the top context - [optional] the template name of the overrides It creates an empty `ConfigMap` resource that you can override with your configuration. @@ -106,7 +106,7 @@ metadata: The `common.deployment` template accepts a list of four values: -- the top context +- `$top`, the top context - `$deployment`, a dictionary of values used in the deployment template - `$autoscaling`, a dictionary of values used in the hpa template - [optional] the template name of the overrides @@ -123,16 +123,7 @@ It defines a basic `Deployment` with the following settings: | `$deployment.tolerations` | [optional] Toleration labels for pod assignment | | `$autoscaling.enabled` | [optional] Set this to `true` to enable autoscaling | -Underneath the hood, it uses [`common.container`](#commoncontainer). - -By default, the pod template within the deployment defines the labels - -```yaml -app.kubernetes.io/name: {{ include "common.name" }} -app.kubernetes.io/instance: {{ .Release.Name }} -``` - -as this is also used as the selector. The standard set of labels are not used as some of these can change during upgrades, which causes the replica sets and pods to not correctly match. +Underneath the hood, it invokes [`common.pod.template`](#commonpodtemplate) template with `$deployment` to populate the `PodTemplate`. Example use: @@ -151,7 +142,7 @@ Example use: The `common.ingress` template accepts a list of four values: -- the top context +- `$top`, the top context - `$ingress`, a dictionary of values used in the ingress template - `$service`, a dictionary of values used in the service template - [optional] the template name of the overrides @@ -225,7 +216,7 @@ spec: The `common.secret` template accepts a list of two values: -- the top context +- `$top`, the top context - [optional] the template name of the overrides It creates an empty `Secret` resource that you can override with your secrets. @@ -271,7 +262,7 @@ type: Opaque The `common.service` template accepts a list of three values: -- the top context +- `$top`, the top context - `$service`, a dictionary of values used in the service template - [optional] the template name of the overrides @@ -293,18 +284,18 @@ Example template: {{- define "mychart.mail.service" -}} {{- $top := first . -}} metadata: - name: {{ include "common.fullname" $top }}-mail # overrides the default name to add a suffix - labels: # appended to the labels section + name: {{ include "common.fullname" $top }}-mail # overrides the default name to add a suffix + labels: # appended to the labels section protocol: mail spec: - ports: # composes the `ports` section of the service definition. + ports: # composes the `ports` section of the service definition. - name: smtp port: 25 targetPort: 25 - name: imaps port: 993 targetPort: 993 - selector: # this is appended to the default selector + selector: # this is appended to the default selector protocol: mail {{- end }} --- @@ -312,11 +303,11 @@ spec: {{- define "mychart.web.service" -}} {{- $top := first . -}} metadata: - name: {{ include "common.fullname" $top }}-www # overrides the default name to add a suffix - labels: # appended to the labels section + name: {{ include "common.fullname" $top }}-www # overrides the default name to add a suffix + labels: # appended to the labels section protocol: www spec: - ports: # composes the `ports` section of the service definition. + ports: # composes the `ports` section of the service definition. - name: www port: 80 targetPort: 8080 @@ -389,7 +380,7 @@ When writing Kubernetes resources, you may find the following helpers useful to The `common.container` template accepts a list of three values: -- the top context +- `$top`, the top context - `$container`, a dictionary of values used in the container template - [optional] the template name of the overrides @@ -435,7 +426,7 @@ readinessProbe: {{- end -}} ``` -The above example creates a `Deployment` resource which makes use of the `common.container` template to populate the PodSpec's container list. The usage of this template is similar to the other resources, you must define and reference a template that contains overrides for the container object. +The above example creates a `Deployment` resource which makes use of the `common.container` template to populate the `PodSpec`'s container list. The usage of this template is similar to the other resources, you must define and reference a template that contains overrides for the container object. The most important part of a container definition is the image you want to run. As mentioned above, this is derived from `$container.image` by default. It is a best practice to define the image, tag and pull policy in your charts' values as this makes it easy for an operator to change the image registry, or use a specific tag or version. Another example of configuration that should be exposed to chart operators is the container's required compute resources, as this is also very specific to an operators environment. An example `values.yaml` for your chart could look like: @@ -518,3 +509,35 @@ spec: runAsUser: 1000 serviceAccountName: release-name-mychart ``` + + + +### `common.pod.template` + +The `common.pod.template` template accepts a list of three values: + +- `$top`, the top context +- `$pod`, a dictionary of values used in the container template +- [optional] the template name of the overrides + +It creates a basic `PodTemplate` spec to be used within a `Deployment` or `CronJob`. It holds the following defaults: + +- Defines the labels + ```yaml + app.kubernetes.io/name: {{ include "common.name" }} + app.kubernetes.io/instance: {{ .Release.Name }} + ``` + as this is also used as the selector. +- Service account name is set with `{{ include "common.serviceAccountName" $top }}` + +It also uses the following configuration from the `$pod`: + +| Value | Description | +| ----- | ----------- | +| `$pod.imagePullSecrets` | Names of secrets containing private registry credentials | +| `$pod.podSecurityContext` | Security options | +| `$pod.nodeSelector ` | Node labels for pod assignment | +| `$pod.affinity ` | Expressions for affinity | +| `$pod.tolerations ` | Toleration labels for pod assignment | + +Underneath the hood, it invokes [`common.container`](#commoncontainer) template with `$pod` to populate the `PodSpec`'s container list. \ No newline at end of file From 98652addbc72aa94c5c41948262520d2379ede5c Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 11:34:40 +0800 Subject: [PATCH 16/37] docs: add link to `common.pod.template` --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index e33b811..535f426 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.service`](#commonservice) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) + * [`common.pod.template`](#commonpodtemplate) From 70530640c5367f271b3c92a9dd089aafbe02e64b Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 11:39:06 +0800 Subject: [PATCH 17/37] refactor: correct indentations --- templates/_pod.tpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/_pod.tpl b/templates/_pod.tpl index 76fa0b2..12a048e 100644 --- a/templates/_pod.tpl +++ b/templates/_pod.tpl @@ -9,7 +9,7 @@ metadata: spec: {{- with $pod.imagePullSecrets }} imagePullSecrets: - {{- toYaml . | nindent 8 }} + {{- toYaml . | nindent 4 }} {{- end }} serviceAccountName: {{ include "common.serviceAccountName" $top }} securityContext: From a5d01023679560683a286b3660eb8f855d6e2ccf Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 12:17:28 +0800 Subject: [PATCH 18/37] docs: add description about `common.serviceAccount` --- README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 535f426..3f5a970 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.ingress`](#commoningress) * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) + * [`common.serviceAccount`](#commonserviceaccount) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) * [`common.pod.template`](#commonpodtemplate) @@ -371,6 +372,56 @@ spec: +### `common.serviceAccount` + +The `common.serviceAccount` template accepts a list of three values: + +- `$top`, the top context +- `$serviceAccount`, a dictionary of values used in the service account template +- [optional] the template name of the overrides + +It creates a basic `ServiceAccount` resource with the following defaults: + +- The name is set with `common.serviceAccountName` +- Lays out the annotations using `$serviceAccount.annotations` + +An example values file that can be used to configure the `ServiceAccount` resource is: + +```yaml +serviceAccount: + create: true + annotations: {} + name: +``` + +Example use: + +```yaml +{{- include "common.serviceAccount" (list . .Values.serviceAccount) -}} + +## The following is the same as above: +# {{- include "common.serviceAccount" (list . .Values.serviceAccount "mychart.serviceAccount") -}} +# {{- define "mychart.serviceAccount" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +``` + + + ## Partial Objects When writing Kubernetes resources, you may find the following helpers useful to construct parts of the spec. @@ -529,7 +580,7 @@ It creates a basic `PodTemplate` spec to be used within a `Deployment` or `CronJ app.kubernetes.io/instance: {{ .Release.Name }} ``` as this is also used as the selector. -- Service account name is set with `{{ include "common.serviceAccountName" $top }}` +- Service account name is set with `common.serviceAccountName` It also uses the following configuration from the `$pod`: From 958453fd4c7d190bc67cf6ae0171407621aee13e Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 12:56:42 +0800 Subject: [PATCH 19/37] docs: add description about `common.cronJob` --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/README.md b/README.md index 3f5a970..ef4e6a3 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen - [Resource Kinds](#resource-kinds) * [`common.configMap`](#commonconfigmap) + * [`common.cronJob`](#commoncronjob) * [`common.deployment`](#commondeployment) * [`common.ingress`](#commoningress) * [`common.secret`](#commonsecret) @@ -104,6 +105,50 @@ metadata: +### `common.cronJob` + +The `common.cronJob` template accepts a list of four values: + +- `$top`, the top context +- `$cronJob`, a dictionary of values used in the cronjob template +- `$pod`, a dictionary of values used in the pod template +- [optional] the template name of the overrides + +It defines a basic `CronJob` with the following defaults: + +- Defines the labels of `JobTemplate` + ```yaml + app.kubernetes.io/name: {{ include "common.name" }} + app.kubernetes.io/instance: {{ .Release.Name }} + ``` + as this is also used as the selector. +- Restart policy of pod is set to `OnFailure` + +In addition, it uses the following configuration from the `$cronJob`: + +| Value | Description | +| ----- | ----------- | +| `$cronJob.schedule` | Schedule for the cronjob | +| `$cronJob.concurrencyPolicy` | [optional] `Allow\|Forbid\|Replace` concurrent jobs | +| `$cronJob.failedJobsHistoryLimit` | [optional] Specify the number of failed jobs to keep | +| `$cronJob.successfulJobsHistoryLimit` | [optional] Specify the number of completed jobs to keep | + +Underneath the hood, it invokes [`common.pod.template`](#commonpodtemplate) template with `$pod` to populate the `PodTemplate`. + +Example use: + +```yaml +{{- include "common.cronJob" (list . .Values.cronJob .Values) -}} + +## The following is the same as above: +# {{- include "common.cronJob" (list . .Values.cronJob .Values "mychart.cronJob") -}} +# {{- define "mychart.cronJob" -}} +# {{- end -}} +``` + + + + ### `common.deployment` The `common.deployment` template accepts a list of four values: From 8690a9353ec62c9fcaafdc64b3643da7a088dc5b Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 13:28:16 +0800 Subject: [PATCH 20/37] docs: add description about `common.hpa` --- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/README.md b/README.md index ef4e6a3..2c44e83 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.configMap`](#commonconfigmap) * [`common.cronJob`](#commoncronjob) * [`common.deployment`](#commondeployment) + * [`common.hpa`](#commonhpa) * [`common.ingress`](#commoningress) * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) @@ -185,6 +186,77 @@ Example use: +### `common.hpa` + +The `common.hpa` template accepts a list of three values: + +- `$top`, the top context +- `$autoscaling`, a dictionary of values used in the hpa template +- [optional] the template name of the overrides + +It creates a basic `HorizontalPodAutoscaler` resource with the following defaults: + +- The name of scaled target is set with `"common.fullname"` + +An example values file that can be used to configure the `HorizontalPodAutoscaler` resource is: + +```yaml +autoscaling: + enabled: true + minReplicas: 3 + maxReplicas: 5 + cpuUtilizationPercentage: 50 + memoryUtilizationPercentage: 90 +``` + +Example use: + +```yaml +{{- include "common.hpa" (list . .Values.autoscaling) -}} + +## The following is the same as above: +# {{- include "common.hpa" (list . .Values.autoscaling "mychart.hpa") -}} +# {{- define "mychart.hpa" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: autoscaling/v2beta2 +kind: HorizontalPodAutoscaler +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +spec: + maxReplicas: 5 + metrics: + - resource: + name: cpu + target: + averageUtilization: 50 + type: Utilization + type: Resource + - resource: + name: memory + target: + averageUtilization: 90 + type: Utilization + type: Resource + minReplicas: 3 + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: release-name-mychart +``` + + + ### `common.ingress` The `common.ingress` template accepts a list of four values: From 0866ba1a51b0a1196e99269542b80cb600eaeb2e Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 14:02:58 +0800 Subject: [PATCH 21/37] docs: add description about `common.pdb` --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/README.md b/README.md index 2c44e83..5dbc003 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.deployment`](#commondeployment) * [`common.hpa`](#commonhpa) * [`common.ingress`](#commoningress) + * [`common.pdb`](#commonpdb) * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) * [`common.serviceAccount`](#commonserviceaccount) @@ -331,6 +332,68 @@ spec: +### `common.pdb` + +The `common.pdb` template accepts a list of five values: + +- `$top`, the top context +- `$pdb`, a dictionary of values used in the hpa template +- `$deployment`, a dictionary of values used in the deployment template +- `$autoscaling`, a dictionary of values used in the hpa template +- [optional] the template name of the overrides + +It creates a basic `PodDisruptionBudget` resource with the following defaults: + +- Selector is set to + ```yaml + app.kubernetes.io/name: {{ include "common.name" }} + app.kubernetes.io/instance: {{ .Release.Name }} + ``` + to match the default used in the `Pod` resource + +An example values file that can be used to configure the `PodDisruptionBudget` resource is: + +```yaml +podDisruptionBudget: + ## You can specify only one of maxUnavailable and minAvailable in a single PodDisruptionBudget + minAvailable: 2 + # maxUnavailable: 1 +``` + +Example use: + +```yaml +{{- include "common.pdb" (list . .Values.podDisruptionBudget .Values .Values.autoscaling) -}} + +## The following is the same as above: +# {{- include "common.pdb" (list . .Values.podDisruptionBudget .Values .Values.autoscaling "mychart.pdb") -}} +# {{- define "mychart.pdb" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: policy/v1beta1 +kind: PodDisruptionBudget +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +spec: + minAvailable: 2 + selector: + matchLabels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart +``` + + + ### `common.secret` The `common.secret` template accepts a list of two values: From 8a8bb283d1ab4b750e7775c1a882db1b21b2133a Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 14:43:48 +0800 Subject: [PATCH 22/37] docs: add description about `common.serviceMonitor` --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/README.md b/README.md index 5dbc003..b4dbf33 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.secret`](#commonsecret) * [`common.service`](#commonservice) * [`common.serviceAccount`](#commonserviceaccount) + * [`common.serviceMonitor`](#commonservicemonitor) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) * [`common.pod.template`](#commonpodtemplate) @@ -602,6 +603,89 @@ metadata: +### `common.serviceMonitor` + +The `common.serviceMonitor` template accepts a list of three values: + +- `$top`, the top context +- `$serviceMonitor`, a dictionary of values used in the service account template +- [optional] the template name of the overrides + +It creates a basic `ServiceMonitor` resource with the following defaults: + +- Namespace selector is set to the release namespace +- Selector is set to + ```yaml + app.kubernetes.io/name: {{ include "common.name" }} + app.kubernetes.io/instance: {{ .Release.Name }} + ``` + to match the default used in the `Service` resource + +An example values file that can be used to configure the `ServiceMonitor` resource is: + +```yaml +serviceMonitor: + enabled: true + namespace: monitoring + port: 80 + path: /path/to/metrics + interval: 30s + scrapeTimeout: 30s + basicAuth: + enabled: true + username: administrator + password: password +``` + +Example use: + +```yaml +{{- include "common.serviceMonitor" (list . .Values.serviceMonitor) -}} + +## The following is the same as above: +# {{- include "common.serviceMonitor" (list . .Values.serviceMonitor "mychart.serviceMonitor") -}} +# {{- define "mychart.serviceMonitor" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: monitoring.coreos.com/v1 +kind: ServiceMonitor +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart + namespace: monitoring +spec: + endpoints: + - basicAuth: + password: + key: password + name: release-name-mychart + username: + key: username + name: release-name-mychart + interval: 30s + path: /path/to/metrics + port: 80 + scrapeTimeout: 30s + namespaceSelector: + matchNames: + - default + selector: + matchLabels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/name: mychart +``` + + + ## Partial Objects When writing Kubernetes resources, you may find the following helpers useful to construct parts of the spec. From 347f9339f5517c70b92ade32a136beb42ed6e8c5 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 15:13:37 +0800 Subject: [PATCH 23/37] docs: add description about `common.serviceMonitor.secret` --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/README.md b/README.md index b4dbf33..650eb18 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.service`](#commonservice) * [`common.serviceAccount`](#commonserviceaccount) * [`common.serviceMonitor`](#commonservicemonitor) + * [`common.serviceMonitor.secret`](#commonservicemonitorsecret) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) * [`common.pod.template`](#commonpodtemplate) @@ -686,6 +687,59 @@ spec: +### `common.serviceMonitor.secret` + +The `common.serviceMonitor.secret` template accepts a list of three values: + +- `$top`, the top context +- `$serviceMonitor`, a dictionary of values used in the service account template +- [optional] the template name of the overrides + +It creates a `Secret` resource contains the BasicAuth information for the `SecretMonitor`. + +An example `values.yaml` for your `ServiceMonitor` could look like: + +```yaml +serviceMonitor: + basicAuth: + enabled: true + username: administrator + password: password +``` + +Example use: + +```yaml +{{- include "common.serviceMonitor.secret" (list . .Values.serviceMonitor) -}} + +## The following is the same as above: +# {{- include "common.serviceMonitor.secret" (list . .Values.serviceMonitor "mychart.serviceMonitor.secret") -}} +# {{- define "mychart.serviceMonitor.secret" -}} +# {{- end -}} +``` + +Output: + +```yaml +apiVersion: v1 +data: + password: cGFzc3dvcmQ= + username: YWRtaW5pc3RyYXRvcg== +kind: Secret +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart + namespace: monitoring +type: Opaque +``` + + + ## Partial Objects When writing Kubernetes resources, you may find the following helpers useful to construct parts of the spec. From 74d49b39707bd7c1d146d5c547dc1c84154ffb3c Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 15:26:05 +0800 Subject: [PATCH 24/37] docs: add description about `common.metadata` --- README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/README.md b/README.md index 650eb18..5fc0690 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.serviceMonitor.secret`](#commonservicemonitorsecret) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) + * [`common.metadata`](#commonmetadata) * [`common.pod.template`](#commonpodtemplate) @@ -882,6 +883,47 @@ spec: +### `common.metadata` + +The `common.metadata` helper generates value for the `metadata:` section of a Kubernetes resource. + +This takes a list of two values: + +- `$top`, the top context +- [optional] the template name of the overrides + +It generates standard labels and a name field. + +Example template: + +```yaml +metadata: + {{- include "common.metadata" (list .) | nindent 2 }} + +## The following is the same as above: +# metadata: +# {{- include "common.metadata" (list . "mychart.metadata") | nindent 2 }} +# {{- define "mychart.metadata" -}} +# {{- end -}} +``` + +Example output: + +```yaml +metadata: + labels: + app.kubernetes.io/instance: release-name + app.kubernetes.io/managed-by: Helm + app.kubernetes.io/name: mychart + app.kubernetes.io/version: 1.16.0 + helm.sh/chart: mychart-0.1.0 + name: release-name-mychart +``` + +Most of the common templates that define a resource type (e.g. `common.configMap` or `common.cronJob`) use this to generate the metadata, which means they inherit the same `labels` and `name` fields. + + + ### `common.pod.template` The `common.pod.template` template accepts a list of three values: From 8463dcfa6fed7d13a2def6e5b5cf5e2cdf8f33d7 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 15:36:48 +0800 Subject: [PATCH 25/37] docs: add description about `common.selectorLabels` --- README.md | 57 +++++++++++++++++++++++++------------------------------ 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 5fc0690..50017f0 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.container`](#commoncontainer) * [`common.metadata`](#commonmetadata) * [`common.pod.template`](#commonpodtemplate) + * [`common.selectorLabels`](#commonselectorlabels) @@ -121,12 +122,7 @@ The `common.cronJob` template accepts a list of four values: It defines a basic `CronJob` with the following defaults: -- Defines the labels of `JobTemplate` - ```yaml - app.kubernetes.io/name: {{ include "common.name" }} - app.kubernetes.io/instance: {{ .Release.Name }} - ``` - as this is also used as the selector. +- Labels of `JobTemplate` are defined with [`common.selectorLabels`](#commonselectorlabels) as this is also used as the selector. - Restart policy of pod is set to `OnFailure` In addition, it uses the following configuration from the `$cronJob`: @@ -347,12 +343,7 @@ The `common.pdb` template accepts a list of five values: It creates a basic `PodDisruptionBudget` resource with the following defaults: -- Selector is set to - ```yaml - app.kubernetes.io/name: {{ include "common.name" }} - app.kubernetes.io/instance: {{ .Release.Name }} - ``` - to match the default used in the `Pod` resource +- Selector is set with [`common.selectorLabels`](#commonselectorlabels) to match the default used in the `Pod` resource An example values file that can be used to configure the `PodDisruptionBudget` resource is: @@ -455,12 +446,7 @@ It creates a basic `Service` resource with the following defaults: - Service type (ClusterIP, NodePort, LoadBalancer) made configurable by `$service.type` - Named port `http` configured on port `$service.port` -- Selector set to - ```yaml - app.kubernetes.io/name: {{ include "common.name" }} - app.kubernetes.io/instance: {{ .Release.Name }} - ``` - to match the default used in the `Deployment` resource +- Selector set with [`common.selectorLabels`](#commonselectorlabels) to match the default used in the `Deployment` resource Example template: @@ -616,12 +602,7 @@ The `common.serviceMonitor` template accepts a list of three values: It creates a basic `ServiceMonitor` resource with the following defaults: - Namespace selector is set to the release namespace -- Selector is set to - ```yaml - app.kubernetes.io/name: {{ include "common.name" }} - app.kubernetes.io/instance: {{ .Release.Name }} - ``` - to match the default used in the `Service` resource +- Selector is set with [`common.selectorLabels`](#commonselectorlabels) to match the default used in the `Service` resource An example values file that can be used to configure the `ServiceMonitor` resource is: @@ -934,12 +915,7 @@ The `common.pod.template` template accepts a list of three values: It creates a basic `PodTemplate` spec to be used within a `Deployment` or `CronJob`. It holds the following defaults: -- Defines the labels - ```yaml - app.kubernetes.io/name: {{ include "common.name" }} - app.kubernetes.io/instance: {{ .Release.Name }} - ``` - as this is also used as the selector. +- Labels are defined with [`common.selectorLabels`](#commonselectorlabels) as this is also used as the selector. - Service account name is set with `common.serviceAccountName` It also uses the following configuration from the `$pod`: @@ -952,4 +928,23 @@ It also uses the following configuration from the `$pod`: | `$pod.affinity ` | Expressions for affinity | | `$pod.tolerations ` | Toleration labels for pod assignment | -Underneath the hood, it invokes [`common.container`](#commoncontainer) template with `$pod` to populate the `PodSpec`'s container list. \ No newline at end of file +Underneath the hood, it invokes [`common.container`](#commoncontainer) template with `$pod` to populate the `PodSpec`'s container list. + + + +### `common.selectorLabels` + +`common.selectorLabels` prints the standard set of selector labels. + +Example usage: + +``` +{{ include "common.selectorLabels" . }} +``` + +Example output: + +```yaml +app.kubernetes.io/instance: release-name +app.kubernetes.io/name: mychart +``` \ No newline at end of file From 231146eba788993e5e975cc2bd9ef50f970b9e67 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 15:38:58 +0800 Subject: [PATCH 26/37] docs: add description about `common.labels` --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/README.md b/README.md index 50017f0..95a095e 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.serviceMonitor.secret`](#commonservicemonitorsecret) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) + * [`common.labels`](#commonlabels) * [`common.metadata`](#commonmetadata) * [`common.pod.template`](#commonpodtemplate) * [`common.selectorLabels`](#commonselectorlabels) @@ -864,6 +865,28 @@ spec: +### `common.labels` + +`common.selectorLabels` prints the standard set of labels. + +Example usage: + +``` +{{ include "common.labels" . }} +``` + +Example output: + +```yaml +app.kubernetes.io/instance: release-name +app.kubernetes.io/managed-by: Helm +app.kubernetes.io/name: mychart +app.kubernetes.io/version: 1.16.0 +helm.sh/chart: mychart-0.1.0 +``` + + + ### `common.metadata` The `common.metadata` helper generates value for the `metadata:` section of a Kubernetes resource. From 264d45a56454480ed09638c6b9dfbfe654d57086 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 15:42:36 +0800 Subject: [PATCH 27/37] refactor: remove duplicate template `common.labels` --- templates/_name.tpl | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/templates/_name.tpl b/templates/_name.tpl index 49b0d49..4c27502 100644 --- a/templates/_name.tpl +++ b/templates/_name.tpl @@ -32,18 +32,6 @@ Create chart name and version as used by the chart label. {{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}} {{- end -}} -{{/* -Common labels -*/}} -{{- define "common.labels" -}} -helm.sh/chart: {{ include "common.chart" . }} -{{ include "common.selectorLabels" . }} -{{- if .Chart.AppVersion }} -app.kubernetes.io/version: {{ .Chart.AppVersion | quote }} -{{- end }} -app.kubernetes.io/managed-by: {{ .Release.Service }} -{{- end -}} - {{/* Create the name of the service account to use. */}} From 69997fbf2368356eb663501f511db9dfd2d7038e Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 16:06:44 +0800 Subject: [PATCH 28/37] refactor: remove duplicate template `common.name` --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index 95a095e..13ead1e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.container`](#commoncontainer) * [`common.labels`](#commonlabels) * [`common.metadata`](#commonmetadata) + * [`common.name`](#commonname) * [`common.pod.template`](#commonpodtemplate) * [`common.selectorLabels`](#commonselectorlabels) @@ -928,6 +929,35 @@ Most of the common templates that define a resource type (e.g. `common.configMap +### `common.name` + +The `common.name` template generates a name suitable for the `app.kubernetes.io/name` label. It is used like this: + +```yaml +app.kubernetes.io/name: {{ include "common.name" . }} +``` + +This prints the value of `{{ .Chart.Name }}` by default, but can be overridden with `.Values.nameOverride`: + +```yaml +nameOverride: some-name +``` + +Example output: + +```yaml +--- +# with the values above +app.kubernetes.io/name: some-name + +--- +# the default, for chart "mychart" +app.kubernetes.io/name: mychart +``` + +Output of this function is truncated at 63 characters, which is the maximum length of name. + + ### `common.pod.template` The `common.pod.template` template accepts a list of three values: From 1bd3a4c18894f2b0e5e1003de8918fa42e0c36a3 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 16:16:06 +0800 Subject: [PATCH 29/37] refactor: remove duplicate template `common.fullname` --- README.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 13ead1e..5fc3da1 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.serviceMonitor.secret`](#commonservicemonitorsecret) - [Partial Objects](#partial-objects) * [`common.container`](#commoncontainer) + * [`common.fullname`](#commonfullname) * [`common.labels`](#commonlabels) * [`common.metadata`](#commonmetadata) * [`common.name`](#commonname) @@ -198,7 +199,7 @@ The `common.hpa` template accepts a list of three values: It creates a basic `HorizontalPodAutoscaler` resource with the following defaults: -- The name of scaled target is set with `"common.fullname"` +- The name of scaled target is set with [`common.fullname`](#commonfullname) An example values file that can be used to configure the `HorizontalPodAutoscaler` resource is: @@ -866,6 +867,36 @@ spec: +### `common.fullname` + +The `common.fullname` template generates a name suitable for the `name:` field in Kubernetes metadata. It is used like this: + +```yaml +name: {{ include "common.fullname" . }} +``` + +This prints the value of `{{ .Release.Name }}-{{ .Chart.Name }}` by default, but can be overridden with `.Values. fullnameOverride`: + +```yaml +fullnameOverride: some-name +``` + +Example output: + +```yaml +--- +# with the values above +name: some-name + +--- +# the default, for release "release-name" and chart "mychart" +name: release-name-mychart +``` + +Output of this function is truncated at 63 characters, which is the maximum length of name. + + + ### `common.labels` `common.selectorLabels` prints the standard set of labels. From b5cae82278c894a407f8a4150325b45b0ee5c2bc Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 16:19:20 +0800 Subject: [PATCH 30/37] refactor: remove duplicate template `common.chart` --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 5fc3da1..4e70d6f 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.serviceMonitor`](#commonservicemonitor) * [`common.serviceMonitor.secret`](#commonservicemonitorsecret) - [Partial Objects](#partial-objects) + * [`common.chart`](#commonchart) * [`common.container`](#commoncontainer) * [`common.fullname`](#commonfullname) * [`common.labels`](#commonlabels) @@ -731,6 +732,26 @@ When writing Kubernetes resources, you may find the following helpers useful to +### `common.chart` + +The `common.chart` helper prints the chart name and version, escaped to be legal in a Kubernetes label field. + +Example template: + +```yaml +helm.sh/chart: {{ include "common.chart" . }} +``` + +For the chart `foo` with version `1.2.3-beta.55+1234`, this will render: + +```yaml +helm.sh/chart: foo-1.2.3-beta.55_1234 +``` + +(Note that `+` is an illegal character in label values) + + + ### `common.container` The `common.container` template accepts a list of three values: From 9bd8494e4fba870e51a99e479d975579ef83f3da Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 16:35:21 +0800 Subject: [PATCH 31/37] fix: `common.serviceAccountName` should accepts `$serviceAccount` --- README.md | 17 ++++++++++------- templates/_cronjob.yaml | 3 ++- templates/_deployment.yaml | 3 ++- templates/_name.tpl | 5 +++-- templates/_pod.tpl | 5 +++-- templates/_serviceaccount.yaml | 2 +- 6 files changed, 21 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4e70d6f..a693bf0 100644 --- a/README.md +++ b/README.md @@ -117,11 +117,12 @@ metadata: ### `common.cronJob` -The `common.cronJob` template accepts a list of four values: +The `common.cronJob` template accepts a list of five values: - `$top`, the top context - `$cronJob`, a dictionary of values used in the cronjob template - `$pod`, a dictionary of values used in the pod template +- `$serviceAccount`, a dictionary of values used in the service account template - [optional] the template name of the overrides It defines a basic `CronJob` with the following defaults: @@ -143,10 +144,10 @@ Underneath the hood, it invokes [`common.pod.template`](#commonpodtemplate) temp Example use: ```yaml -{{- include "common.cronJob" (list . .Values.cronJob .Values) -}} +{{- include "common.cronJob" (list . .Values.cronJob .Values .Values.serviceAccount) -}} ## The following is the same as above: -# {{- include "common.cronJob" (list . .Values.cronJob .Values "mychart.cronJob") -}} +# {{- include "common.cronJob" (list . .Values.cronJob .Values .Values.serviceAccount "mychart.cronJob") -}} # {{- define "mychart.cronJob" -}} # {{- end -}} ``` @@ -156,11 +157,12 @@ Example use: ### `common.deployment` -The `common.deployment` template accepts a list of four values: +The `common.deployment` template accepts a list of five values: - `$top`, the top context - `$deployment`, a dictionary of values used in the deployment template - `$autoscaling`, a dictionary of values used in the hpa template +- `$serviceAccount`, a dictionary of values used in the service account template - [optional] the template name of the overrides It defines a basic `Deployment` with the following settings: @@ -180,10 +182,10 @@ Underneath the hood, it invokes [`common.pod.template`](#commonpodtemplate) temp Example use: ```yaml -{{- include "common.deployment" (list . .Values .Values.autoscaling) -}} +{{- include "common.deployment" (list . .Values .Values.autoscaling .Values.serviceAccount) -}} ## The following is the same as above: -# {{- include "common.deployment" (list . .Values .Values.autoscaling "mychart.deployment") -}} +# {{- include "common.deployment" (list . .Values .Values.autoscaling .Values.serviceAccount "mychart.deployment") -}} # {{- define "mychart.deployment" -}} # {{- end -}} ``` @@ -1012,10 +1014,11 @@ Output of this function is truncated at 63 characters, which is the maximum leng ### `common.pod.template` -The `common.pod.template` template accepts a list of three values: +The `common.pod.template` template accepts a list of four values: - `$top`, the top context - `$pod`, a dictionary of values used in the container template +- `$serviceAccount`, a dictionary of values used in the service account template - [optional] the template name of the overrides It creates a basic `PodTemplate` spec to be used within a `Deployment` or `CronJob`. It holds the following defaults: diff --git a/templates/_cronjob.yaml b/templates/_cronjob.yaml index 6aec3a1..4864d5e 100644 --- a/templates/_cronjob.yaml +++ b/templates/_cronjob.yaml @@ -9,6 +9,7 @@ spec: {{- $top := first . -}} {{- $cronJob := index . 1 -}} {{- $pod := index . 2 -}} +{{- $serviceAccount := index . 3 -}} apiVersion: batch/v1beta1 kind: CronJob metadata: @@ -30,7 +31,7 @@ spec: {{- include "common.selectorLabels" $top | nindent 8 }} spec: template: - {{- include "common.pod.template" (list $top $pod "common.cronJob.pod") | nindent 8 }} + {{- include "common.pod.template" (list $top $pod $serviceAccount "common.cronJob.pod") | nindent 8 }} {{- end -}} {{- define "common.cronJob" -}} diff --git a/templates/_deployment.yaml b/templates/_deployment.yaml index 0f6e9ae..b26f079 100644 --- a/templates/_deployment.yaml +++ b/templates/_deployment.yaml @@ -4,6 +4,7 @@ {{- $top := first . -}} {{- $deployment := index . 1 -}} {{- $autoscaling := index . 2 -}} +{{- $serviceAccount := index . 3 -}} apiVersion: apps/v1 kind: Deployment metadata: @@ -16,7 +17,7 @@ spec: matchLabels: {{- include "common.selectorLabels" $top | nindent 6 }} template: - {{- include "common.pod.template" . | nindent 4 }} + {{- include "common.pod.template" (list $top $deployment $serviceAccount) | nindent 4 }} {{- end -}} {{- define "common.deployment" -}} diff --git a/templates/_name.tpl b/templates/_name.tpl index 4c27502..9e6d873 100644 --- a/templates/_name.tpl +++ b/templates/_name.tpl @@ -36,9 +36,10 @@ Create chart name and version as used by the chart label. Create the name of the service account to use. */}} {{- define "common.serviceAccountName" -}} -{{- $serviceAccount := .Values.serviceAccount | default (dict) -}} +{{- $top := first . -}} +{{- $serviceAccount := index . 1 -}} {{- if $serviceAccount.create -}} - {{ default (include "common.fullname" .) $serviceAccount.name }} + {{ default (include "common.fullname" $top) $serviceAccount.name }} {{- else -}} {{ default "default" $serviceAccount.name }} {{- end -}} diff --git a/templates/_pod.tpl b/templates/_pod.tpl index 12a048e..72d4c7c 100644 --- a/templates/_pod.tpl +++ b/templates/_pod.tpl @@ -3,6 +3,7 @@ {{- define "common.pod.template.tpl" -}} {{- $top := first . -}} {{- $pod := index . 1 -}} +{{- $serviceAccount := index . 2 -}} metadata: labels: {{- include "common.selectorLabels" $top | nindent 4 }} @@ -11,11 +12,11 @@ spec: imagePullSecrets: {{- toYaml . | nindent 4 }} {{- end }} - serviceAccountName: {{ include "common.serviceAccountName" $top }} + serviceAccountName: {{ include "common.serviceAccountName" (list $top $serviceAccount) }} securityContext: {{- toYaml $pod.podSecurityContext | nindent 4 }} containers: - - {{- include "common.container" . | nindent 6 }} + - {{- include "common.container" (list $top $pod) | nindent 6 }} {{- with $pod.nodeSelector }} nodeSelector: {{- toYaml . | nindent 4 }} diff --git a/templates/_serviceaccount.yaml b/templates/_serviceaccount.yaml index 82b79ab..ff0c9bb 100644 --- a/templates/_serviceaccount.yaml +++ b/templates/_serviceaccount.yaml @@ -3,7 +3,7 @@ {{- define "common.serviceAccount.metadata" -}} {{- $top := first . -}} {{- $serviceAccount := index . 1 -}} -name: {{ include "common.serviceAccountName" $top }} +name: {{ include "common.serviceAccountName" . }} {{- with $serviceAccount.annotations }} annotations: {{- toYaml . | nindent 2 }} From 9e1d01e3710ae74dbafcb1d36e39b75684b7831b Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 17:04:46 +0800 Subject: [PATCH 32/37] docs: add description about `common.serviceAccountName` --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a693bf0..695c3ef 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen * [`common.name`](#commonname) * [`common.pod.template`](#commonpodtemplate) * [`common.selectorLabels`](#commonselectorlabels) + * [`common.serviceAccountName`](#commonserviceaccountname) @@ -557,7 +558,7 @@ The `common.serviceAccount` template accepts a list of three values: It creates a basic `ServiceAccount` resource with the following defaults: -- The name is set with `common.serviceAccountName` +- The name is set with [`common.serviceAccountName`](#commonserviceaccountname) - Lays out the annotations using `$serviceAccount.annotations` An example values file that can be used to configure the `ServiceAccount` resource is: @@ -1024,7 +1025,7 @@ The `common.pod.template` template accepts a list of four values: It creates a basic `PodTemplate` spec to be used within a `Deployment` or `CronJob`. It holds the following defaults: - Labels are defined with [`common.selectorLabels`](#commonselectorlabels) as this is also used as the selector. -- Service account name is set with `common.serviceAccountName` +- Service account name is set with [`common.serviceAccountName`](#commonserviceaccountname) It also uses the following configuration from the `$pod`: @@ -1055,4 +1056,48 @@ Example output: ```yaml app.kubernetes.io/instance: release-name app.kubernetes.io/name: mychart +``` + + + +### `common.serviceAccountName` + +The `common.serviceAccountName` template accepts a list of three values: + +- `$top`, the top context +- `$serviceAccount`, a dictionary of values used in the service account template +- [optional] the template name of the overrides + +It generates a name suitable for the `serviceAccountName` field of a `Pod` resource. It is used like this: + +An example values file that can be used to configure the HorizontalPodAutoscaler resource is: + +```yaml +serviceAccount: + create: true + # The name of the service account to use. + # If not set and create is true, a name is generated using the fullname template + name: some-name +``` + +Example usage: + +``` +serviceAccountName: {{ include "common.serviceAccountName" . .Values.serviceAccount }} +``` + +Example output: + +```yaml +--- +# with the values above +serviceAccountName: some-name + +--- +# if serviceAccount.name is not set, the value will be the same as "common.fullname" +serviceAccountName: release-name-mychart + +--- +# if serviceAccount.create is false, the value will be "default" +serviceAccountName: default ``` \ No newline at end of file From b276dbc9da604e6d7574ebf28659a32ddba29975 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 17:05:37 +0800 Subject: [PATCH 33/37] fix: correct rendering condition of PDB --- templates/_pdb.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/_pdb.yaml b/templates/_pdb.yaml index c163abf..815997b 100644 --- a/templates/_pdb.yaml +++ b/templates/_pdb.yaml @@ -26,7 +26,7 @@ spec: {{- $top := first . -}} {{- $deployment := index . 2 -}} {{- $autoscaling := index . 3 -}} -{{- if or (and $autoscaling.enabled (gt ($autoscaling.minReplicas | int) 1)) (gt ($deployment.replicaCount | int) 1) }} +{{- if or (and $autoscaling.enabled (gt ($autoscaling.minReplicas | int) 1)) (and (not $autoscaling.enabled) (gt ($deployment.replicaCount | int) 1)) }} {{- include "common.utils.merge" (append . "common.pdb.tpl") -}} {{- end -}} {{- end -}} From f3e9ed48857437da40d4af6af3cda521ac17fb1e Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 17:09:35 +0800 Subject: [PATCH 34/37] docs: remove third parameter of `common.serviceAccountName` --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 695c3ef..33d8848 100644 --- a/README.md +++ b/README.md @@ -1062,11 +1062,10 @@ app.kubernetes.io/name: mychart ### `common.serviceAccountName` -The `common.serviceAccountName` template accepts a list of three values: +The `common.serviceAccountName` template accepts a list of two values: - `$top`, the top context - `$serviceAccount`, a dictionary of values used in the service account template -- [optional] the template name of the overrides It generates a name suitable for the `serviceAccountName` field of a `Pod` resource. It is used like this: From 13b0e663b896d34d811af1d09124ad7197a127b4 Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Thu, 23 Apr 2020 17:12:45 +0800 Subject: [PATCH 35/37] docs: correct description about `common.serviceAccountName` --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 33d8848..023c499 100644 --- a/README.md +++ b/README.md @@ -1067,9 +1067,15 @@ The `common.serviceAccountName` template accepts a list of two values: - `$top`, the top context - `$serviceAccount`, a dictionary of values used in the service account template -It generates a name suitable for the `serviceAccountName` field of a `Pod` resource. It is used like this: +It generates a name suitable for the `serviceAccountName` field of a `Pod` resource. -An example values file that can be used to configure the HorizontalPodAutoscaler resource is: +Example usage: + +``` +serviceAccountName: {{ include "common.serviceAccountName" . .Values.serviceAccount }} +``` + +The following values can influence the output: ```yaml serviceAccount: @@ -1079,12 +1085,6 @@ serviceAccount: name: some-name ``` -Example usage: - -``` -serviceAccountName: {{ include "common.serviceAccountName" . .Values.serviceAccount }} -``` - Example output: ```yaml From 4e227b9daa7256cd86ac844df3730faa45e5fe2f Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Fri, 24 Apr 2020 10:17:57 +0800 Subject: [PATCH 36/37] docs: add "Installation" section --- README.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 023c499..7bbec2d 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ It provides utilities that reflect best practices of Kubernetes chart developmen ## Contents +- [Installation](#installation) - [Resource Kinds](#resource-kinds) * [`common.configMap`](#commonconfigmap) * [`common.cronJob`](#commoncronjob) @@ -33,6 +34,25 @@ It provides utilities that reflect best practices of Kubernetes chart developmen +## Installation + +To use the library chart, `common` should be listed in `dependencies` field in your `Chart.yaml`: + +```yaml +dependencies: + - name: common + version: 0.2.0 + repository: https://hahow-helm-charts.storage.googleapis.com/ +``` + +Once you have defined dependencies, you should run the following command to download this chart into your `charts/` directory: + +```shell +$ helm dependency update +``` + + + ## Resource Kinds Kubernetes defines a variety of resource kinds, from `Secret` to `StatefulSet`. We define some of the most common kinds in a way that lets you easily work with them. @@ -1099,4 +1119,4 @@ serviceAccountName: release-name-mychart --- # if serviceAccount.create is false, the value will be "default" serviceAccountName: default -``` \ No newline at end of file +``` From 512a7ad51cd7df6610727bce5ae396627cc6d94a Mon Sep 17 00:00:00 2001 From: Chi-En Wu Date: Fri, 24 Apr 2020 10:20:55 +0800 Subject: [PATCH 37/37] chore: bump to version 0.3.0 --- Chart.yaml | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Chart.yaml b/Chart.yaml index be62a9f..b6da369 100644 --- a/Chart.yaml +++ b/Chart.yaml @@ -14,4 +14,4 @@ type: library # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. -version: 0.2.0 +version: 0.3.0 diff --git a/README.md b/README.md index 7bbec2d..0ec862a 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ To use the library chart, `common` should be listed in `dependencies` field in y ```yaml dependencies: - name: common - version: 0.2.0 + version: 0.3.0 repository: https://hahow-helm-charts.storage.googleapis.com/ ```