Merge pull request #2583 from unguiculus/improve-examples

Improve chart examples

docs/examples/alpine/Chart.yaml

@@ -1,7 +1,7 @@
 name: alpine
 description: Deploy a basic Alpine Linux pod
 version: 0.1.0
-home: https://k8s.io/helm
+home: https://github.com/kubernetes/helm
 sources:
   - https://github.com/kubernetes/helm
 appVersion: 3.3

docs/examples/alpine/README.md

@@ -2,8 +2,6 @@
 
 Run a single pod of Alpine Linux.
 
-This example was generated using the command `helm create alpine`.
-
 The `templates/` directory contains a very simple pod resource with a
 couple of parameters.
 

docs/examples/alpine/templates/_helpers.tpl

@@ -0,0 +1,16 @@
+{{/* vim: set filetype=mustache: */}}
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+*/}}
+{{- define "fullname" -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}

docs/examples/alpine/templates/alpine-pod.yaml

@@ -1,26 +1,23 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: "{{.Release.Name}}-{{.Values.Name}}"
+  name: {{ template "fullname" . }}
   labels:
     # The "heritage" label is used to track which tool deployed a given chart.
     # It is useful for admins who want to see what releases a particular tool
     # is responsible for.
-    heritage: {{.Release.Service | quote }}
+    heritage: {{ .Release.Service }}
     # The "release" convention makes it easy to tie a release to all of the
     # Kubernetes resources that were created as part of that release.
-    release: {{.Release.Name | quote }}
+    release: {{ .Release.Name }}
     # This makes it easy to audit chart usage.
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-  annotations:
+    app: {{ template "name" . }}
-    "helm.sh/created": {{.Release.Time.Seconds | quote }}
 spec:
-  # This shows how to use a simple value. This will look for a passed-in value
+  # This shows how to use a simple value. This will look for a passed-in value called restartPolicy.
-  # called restartPolicy. If it is not found, it will use the default value.
+  restartPolicy: {{ .Values.restartPolicy }}
-  # {{default "Never" .restartPolicy}} is a slightly optimized version of the
-  # more conventional syntax: {{.restartPolicy | default "Never"}}
-  restartPolicy: {{default "Never" .Values.restartPolicy}}
   containers:
   - name: waiter
-    image: "alpine:3.3"
+    image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
-    command: ["/bin/sleep","9000"]
+    imagePullPolicy: {{ .Values.image.pullPolicy }}
+    command: ["/bin/sleep", "9000"]

docs/examples/alpine/values.yaml

@@ -1,2 +1,6 @@
-# The pod name
+image:
-Name: my-alpine
+  repository: alpine
+  tag: 3.3
+  pullPolicy: IfNotPresent
+
+restartPolicy: Never

docs/examples/nginx/Chart.yaml

@@ -6,9 +6,9 @@ keywords:
   - nginx
   - www
   - web
-home: "https://github.com/kubernetes/helm"
+home: https://github.com/kubernetes/helm
 sources:
-  - "https://hub.docker.com/_/nginx/"
+  - https://hub.docker.com/_/nginx/
 maintainers:
   - name: technosophos
     email: mbutcher@deis.com

docs/examples/nginx/README.md

@@ -13,7 +13,7 @@ pattern:
 - A `Deployment` is used to create a Replica Set of nginx pods.
   ([templates/deployment.yaml](templates/deployment.yaml))
 - A `Service` is used to create a gateway to the pods running in the
-  replica set ([templates/svc.yaml](templates/svc.yaml))
+  replica set ([templates/svc.yaml](templates/service.yaml))
 
 The [values.yaml](values.yaml) exposes a few of the configuration options in the
 charts, though there are some that are not exposed there (like

docs/examples/nginx/templates/_helpers.tpl

@@ -2,15 +2,15 @@
 {{/*
 Expand the name of the chart.
 */}}
-{{define "name"}}{{default "nginx" .Values.nameOverride | trunc 63 | trimSuffix "-" }}{{end}}
+{{- define "name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
 
 {{/*
 Create a default fully qualified app name.
-
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
-We truncate at 63 chars because some Kubernetes name fields are limited to this
-(by the DNS naming spec).
 */}}
-{{define "fullname"}}
+{{- define "fullname" -}}
-{{- $name := default "nginx" .Values.nameOverride -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
-{{printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
-{{end}}
+{{- end -}}

docs/examples/nginx/templates/configmap.yaml

@@ -1,15 +1,14 @@
-# This is a simple example of using a config map to create a single page
+# This is a simple example of using a config map to create a single page static site.
-# static site.
 apiVersion: v1
 kind: ConfigMap
 metadata:
-  name: {{template "fullname" .}}
+  name: {{ template "fullname" . }}
   labels:
-    release: {{ .Release.Name | quote }}
+    heritage: {{ .Release.Service }}
-    app: {{template "fullname" .}}
+    release: {{ .Release.Name }}
-    heritage: {{.Release.Service | quote }}
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    app: {{ template "name" . }}
 data:
-  # When the config map is mounted as a volume, these will be created as
+  # When the config map is mounted as a volume, these will be created as files.
-  # files.
+  index.html: {{ .Values.index | quote }}
-  index.html: {{default "Hello" .Values.index | quote}}
   test.txt: test

docs/examples/nginx/templates/deployment.yaml

@@ -4,39 +4,54 @@ metadata:
   # This uses a "fullname" template (see _helpers)
   # Basing names on .Release.Name means that the same chart can be installed
   # multiple times into the same namespace.
-  name: {{template "fullname" .}}
+  name: {{ template "fullname" . }}
   labels:
     # The "heritage" label is used to track which tool deployed a given chart.
     # It is useful for admins who want to see what releases a particular tool
     # is responsible for.
-    heritage: {{ .Release.Service | quote }}
+    heritage: {{ .Release.Service }}
-    # This makes it easy to search for all components of a release using kubectl.
+    # The "release" convention makes it easy to tie a release to all of the
-    release: {{ .Release.Name | quote }}
+    # Kubernetes resources that were created as part of that release.
+    release: {{ .Release.Name }}
     # This makes it easy to audit chart usage.
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    app: {{ template "name" . }}
 spec:
-  replicas: {{default 1 .Values.replicaCount}}
+  replicas: {{ .Values.replicaCount }}
   template:
     metadata:
+{{- if .Values.podAnnotations }}
+      # Allows custom annotations to be specified
+      annotations:
+{{ toYaml .Values.podAnnotations | indent 8 }}
+{{- end }}
       labels:
-        app: {{template "fullname" .}}
+        app: {{ template "name" . }}
-        release: {{.Release.Name | quote }}
+        release: {{ .Release.Name }}
     spec:
       containers:
-      - name: nginx
+        - name: {{ template "name" . }}
-        # Making image configurable is not necessary. Making imageTag configurable
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
-        # is a nice option for the user. Especially in the strange cases like
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
-        # nginx where the base distro is determined by the tag. Using :latest
+          ports:
-        # is frowned upon, using :stable isn't that great either.
+            - name: http
-        image: "{{default "nginx" .Values.image}}:{{default "stable-alpine" .Values.imageTag}}"
+              containerPort: 80
-        imagePullPolicy: {{default "IfNotPresent" .Values.pullPolicy}}
+              protocol: TCP
-        ports:
+          # This (and the volumes section below) mount the config map as a volume.
-        - containerPort: 80
+          volumeMounts:
-        # This (and the volumes section below) mount the config map as a volume.
+            - mountPath: /usr/share/nginx/html
-        volumeMounts:
+              name: wwwdata-volume
-        - mountPath: /usr/share/nginx/html
+          resources:
-          name: wwwdata-volume
+# Allow chart users to specify resources. Usually, no default should be set, so this is left to be a conscious
+# choice to the chart users and avoids that charts don't run out of the box on, e. g., Minikube when high resource
+# requests are specified by default.
+{{ toYaml .Values.resources | indent 12 }}
+    {{- if .Values.nodeSelector }}
+      nodeSelector:
+      # Node selectors can be important on mixed Windows/Linux clusters.
+{{ toYaml .Values.nodeSelector | indent 8 }}
+    {{- end }}
       volumes:
         - name: wwwdata-volume
           configMap:
-            name: {{template "fullname" .}}
+            name: {{ template "fullname" . }}

docs/examples/nginx/templates/post-install-job.yaml

@@ -1,11 +1,18 @@
 apiVersion: batch/v1
 kind: Job
 metadata:
-  name: "{{template "fullname" . }}"
+  name: {{ template "fullname" . }}
   labels:
-    heritage: {{.Release.Service | quote }}
+    # The "heritage" label is used to track which tool deployed a given chart.
-    release: {{.Release.Name | quote }}
+    # It is useful for admins who want to see what releases a particular tool
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    # is responsible for.
+    heritage: {{ .Release.Service }}
+    # The "release" convention makes it easy to tie a release to all of the
+    # Kubernetes resources that were created as part of that release.
+    release: {{ .Release.Name }}
+    # This makes it easy to audit chart usage.
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    app: {{ template "name" . }}
   annotations:
     # This is what defines this resource as a hook. Without this line, the
     # job is considered part of the release.
@@ -13,19 +20,18 @@ metadata:
 spec:
   template:
     metadata:
-      name: "{{template "fullname" . }}"
+      name: {{ template "fullname" . }}
       labels:
-        heritage: {{.Release.Service | quote }}
+        release: {{ .Release.Name }}
-        release: {{.Release.Name | quote }}
+        app: {{ template "name" . }}
-        chart: "{{.Chart.Name}}-{{.Chart.Version}}"
     spec:
       # This shows how to use a simple value. This will look for a passed-in value
       # called restartPolicy. If it is not found, it will use the default value.
-      # {{default "Never" .restartPolicy}} is a slightly optimized version of the
+      # {{ default "Never" .restartPolicy }} is a slightly optimized version of the
-      # more conventional syntax: {{.restartPolicy | default "Never"}}
+      # more conventional syntax: {{ .restartPolicy | default "Never" }}
-      restartPolicy: Never
+      restartPolicy: {{ .Values.restartPolicy }}
       containers:
-      - name: post-install-job
+        - name: post-install-job
-        image: "alpine:3.3"
+          image: "alpine:3.3"
-        # All we're going to do is sleep for a minute, then exit.
+          # All we're going to do is sleep for a while, then exit.
-        command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]
+          command: ["/bin/sleep", "{{ .Values.sleepyTime }}"]

docs/examples/nginx/templates/pre-install-secret.yaml

@@ -3,7 +3,12 @@
 apiVersion: v1
 kind: Secret
 metadata:
-  name: "{{.Release.Name}}-secret"
+  name: {{ template "fullname" . }}
+  labels:
+    heritage: {{ .Release.Service }}
+    release: {{ .Release.Name }}
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    app: {{ template "name" . }}
   # This declares the resource to be a hook. By convention, we also name the
   # file "pre-install-XXX.yaml", but Helm itself doesn't care about file names.
   annotations:

docs/examples/nginx/templates/service-test.yaml

@@ -1,7 +1,12 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: "{{.Release.Name}}-service-test"
+  name: "{{ template "fullname" . }}-service-test"
+  labels:
+    heritage: {{ .Release.Service }}
+    release: {{ .Release.Name }}
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    app: {{ template "name" . }}
   annotations:
     "helm.sh/hook": test-success
 spec:
@@ -9,5 +14,5 @@ spec:
     - name: curl
       image: radial/busyboxplus:curl
       command: ['curl']
-      args:  [ '{{ template "fullname" .}}:{{default 80 .Values.httpPort}}' ]
+      args:  ['{{ template "fullname" . }}:{{ .Values.service.port }}']
   restartPolicy: Never

docs/examples/nginx/templates/service.yaml

@@ -0,0 +1,39 @@
+apiVersion: v1
+kind: Service
+metadata:
+{{- if .Values.service.annotations }}
+  annotations:
+{{ toYaml .Values.service.annotations | indent 4 }}
+{{- end }}
+  labels:
+    app: {{ template "name" . }}
+    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    heritage: {{ .Release.Service }}
+    release: {{ .Release.Name }}
+  name: {{ template "fullname" . }}
+spec:
+# Provides options for the service so chart users have the full choice
+  type: "{{ .Values.service.type }}"
+  clusterIP: "{{ .Values.service.clusterIP }}"
+{{- if .Values.service.externalIPs }}
+  externalIPs:
+{{ toYaml .Values.service.externalIPs | indent 4 }}
+{{- end }}
+{{- if .Values.service.loadBalancerIP }}
+  loadBalancerIP: "{{ .Values.service.loadBalancerIP }}"
+{{- end }}
+{{- if .Values.service.loadBalancerSourceRanges }}
+  loadBalancerSourceRanges:
+{{ toYaml .Values.service.loadBalancerSourceRanges | indent 4 }}
+{{- end }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      protocol: TCP
+      targetPort: http
+      {{- if (and (eq .Values.service.type "NodePort") (not (empty .Values.service.nodePort))) }}
+      nodePort: {{ .Values.service.nodePort }}
+      {{- end }}
+  selector:
+    app: {{ template "name" . }}
+    release: {{ .Release.Name }}

docs/examples/nginx/templates/svc.yaml

@@ -1,18 +0,0 @@
-# This is a service gateway to the replica set created by the deployment.
-# Take a look at the deployment.yaml for general notes about this chart.
-apiVersion: v1
-kind: Service
-metadata:
-  name: {{template "fullname" .}}
-  labels:
-    heritage: {{ .Release.Service | quote }}
-    release: {{ .Release.Name | quote }}
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
-spec:
-  ports:
-  - port: {{default 80 .Values.httpPort}}
-    targetPort: 80
-    protocol: TCP
-    name: http
-  selector:
-    app: {{template "fullname" .}}

docs/examples/nginx/values.yaml

@@ -2,14 +2,8 @@
 # This is a YAML-formatted file.
 # Declare name/value pairs to be passed into your templates.
 
-# See the list at https://hub.docker.com/r/library/nginx/tags/
-imageTag: "1.11.0"
-
-# The port (defined on the service) to access the HTTP server.
-httpPort: 8888
-
-# Number of nginx instances to run
 replicaCount: 1
+restartPolicy: Never
 
 # Evaluated by the post-install hook
 sleepyTime: "10"
@@ -17,3 +11,24 @@ sleepyTime: "10"
 index: >-
   <h1>Hello</h1>
   <p>This is a test</p>
+
+image:
+  repository: nginx
+  tag: 1.11.0
+  pullPolicy: IfNotPresent
+
+service:
+  annotations: {}
+  clusterIP: ""
+  externalIPs: []
+  loadBalancerIP: ""
+  loadBalancerSourceRanges: []
+  type: ClusterIP
+  port: 8888
+  nodePort: ""
+
+podAnnotations: {}
+
+resources: {}
+
+nodeSelector: {}