Updating to the k8s label convention

Closes #4335

Signed-off-by: Matt Farina <matt@mattfarina.com>

cmd/helm/testdata/testcharts/alpine/templates/alpine-pod.yaml

@@ -6,12 +6,12 @@ metadata:
     # 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 }}
+    app.kubernetes.io/managed-by: {{.Release.Service | quote }}
     # 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 }}
+    app.kubernetes.io/instance: {{.Release.Name | quote }}
     # This makes it easy to audit chart usage.
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
     values: {{.Values.test.Name}}
   annotations:
     "helm.sh/created": {{.Release.Time.Seconds | quote }}

cmd/helm/testdata/testcharts/novals/templates/alpine-pod.yaml

@@ -6,12 +6,12 @@ metadata:
     # 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 }}
+    app.kubernetes.io/managed-by: {{.Release.Service | quote }}
     # 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 }}
+    app.kubernetes.io/instance: {{.Release.Name | quote }}
     # This makes it easy to audit chart usage.
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
   annotations:
     "helm.sh/created": {{.Release.Time.Seconds | quote }}
 spec:

cmd/helm/testdata/testcharts/signtest/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

docs/chart_best_practices/labels.md

@@ -10,7 +10,7 @@ An item of metadata should be a label under the following conditions:
 - It is used by Kubernetes to identify this resource
 - It is useful to expose to operators for the purpose of querying the system.
 
-For example, we suggest using `chart: NAME-VERSION` as a label so that operators
+For example, we suggest using `helm.sh/chart: NAME-VERSION` as a label so that operators
 can conveniently find all of the instances of a particular chart to use.
 
 If an item of metadata is not used for querying, it should be set as an annotation
@@ -25,8 +25,12 @@ are recommended, and _should_ be placed onto a chart for global consistency. Tho
 
 Name|Status|Description
 -----|------|----------
-heritage | REC | This should always be set to `{{ .Release.Service }}`. It is for finding all things managed by Tiller.
+`app.kubernetes.io/name` | REC | This should be the app name, reflecting the entire app. Usually `{{ template "name" . }}` is used for this. This is used by many Kubernetes manifests, and is not Helm-specific.
-release | REC | This should be the `{{ .Release.Name }}`.
+`helm.sh/chart` | REC | This should be the chart name and version: `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`.
-chart | REC | This should be the chart name and version: `{{ .Chart.Name }}-{{ .Chart.Version \| replace "+" "_" }}`.
+`app.kubernetes.io/managed-by` | REC | This should always be set to `{{ .Release.Service }}`. It is for finding all things managed by Tiller.
-app | REC | This should be the app name, reflecting the entire app. Usually `{{ template "name" . }}` is used for this. This is used by many Kubernetes manifests, and is not Helm-specific.
+`app.kubernetes.io/instance` | REC | This should be the `{{ .Release.Name }}`. It aid in differentiating between different instances of the same application.
-component | OPT | This is a common label for marking the different roles that pieces may play in an application. For example, `component: frontend`.
+`app.kubernetes.io/version` | OPT | The version of the app and can be set to `{{ .Chart.AppVersion }}`.
+`app.kubernetes.io/component` | OPT | This is a common label for marking the different roles that pieces may play in an application. For example, `app.kubernetes.io/component: frontend`.
+`app.kubernetes.io/part-of` | OPT | When multiple charts or pieces of software are used together to make one application. For example, application software and a database to produce a website. This can be set to the top level application being supported.
+
+You can find more information on the Kubernetes labels, prefixed with `app.kubernetes.io`, in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/).

docs/chart_best_practices/pods.md

@@ -52,11 +52,11 @@ All PodTemplate sections should specify a selector. For example:
 ```yaml
 selector:
   matchLabels:
-      app: MyName
+      app.kubernetes.io/name: MyName
 template:
   metadata:
     labels:
-      app: MyName
+      app.kubernetes.io/name: MyName
 ```
 
 This is a good practice because it makes the relationship between the set and

docs/chart_template_guide/variables.md

@@ -113,11 +113,11 @@ metadata:
   labels:
     # Many helm templates would use `.` below, but that will not work, 
     # however `$` will work here 
-    app: {{ template "fullname" $ }}
+    app.kubernetes.io/name: {{ template "fullname" $ }}
     # I cannot reference .Chart.Name, but I can do $.Chart.Name
-    chart: "{{ $.Chart.Name }}-{{ $.Chart.Version }}"
+    helm.sh/chart: "{{ $.Chart.Name }}-{{ $.Chart.Version }}"
-    release: "{{ $.Release.Name }}"
+    app.kubernetes.io/instance: "{{ $.Release.Name }}"
-    heritage: "{{ $.Release.Service }}"
+    app.kubernetes.io/managed-by: "{{ $.Release.Service }}"
 type: kubernetes.io/tls
 data:
   tls.crt: {{ .certificate }}

docs/charts.md

@@ -526,15 +526,15 @@ metadata:
   name: deis-database
   namespace: deis
   labels:
-    heritage: deis
+    app.kubernetes.io/managed-by: deis
 spec:
   replicas: 1
   selector:
-    app: deis-database
+    app.kubernetes.io/name: deis-database
   template:
     metadata:
       labels:
-        app: deis-database
+        app.kubernetes.io/name: deis-database
     spec:
       serviceAccount: deis-database
       containers:
@@ -663,15 +663,15 @@ metadata:
   name: deis-database
   namespace: deis
   labels:
-    heritage: deis
+    app.kubernetes.io/managed-by: deis
 spec:
   replicas: 1
   selector:
-    app: deis-database
+    app.kubernetes.io/name: deis-database
   template:
     metadata:
       labels:
-        app: deis-database
+        app.kubernetes.io/name: deis-database
     spec:
       serviceAccount: deis-database
       containers:

docs/charts_hooks.md

@@ -127,9 +127,9 @@ kind: Job
 metadata:
   name: "{{.Release.Name}}"
   labels:
-    heritage: {{.Release.Service | quote }}
+    app.kubernetes.io/managed-by: {{.Release.Service | quote }}
-    release: {{.Release.Name | quote }}
+    app.kubernetes.io/instance: {{.Release.Name | quote }}
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
   annotations:
     # This is what defines this resource as a hook. Without this line, the
     # job is considered part of the release.
@@ -141,9 +141,9 @@ spec:
     metadata:
       name: "{{.Release.Name}}"
       labels:
-        heritage: {{.Release.Service | quote }}
+        app.kubernetes.io/managed-by: {{.Release.Service | quote }}
-        release: {{.Release.Name | quote }}
+        app.kubernetes.io/instance: {{.Release.Name | quote }}
-        chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+        helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
     spec:
       restartPolicy: Never
       containers:

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

@@ -3,16 +3,16 @@ kind: Pod
 metadata:
   name: {{ template "alpine.fullname" . }}
   labels:
-    # The "heritage" label is used to track which tool deployed a given chart.
+    # The "app.kubernetes.io/managed-by" 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 }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    # The "release" convention makes it easy to tie a release to all of the
+    # The "app.kubernetes.io/instance" 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 }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
     # This makes it easy to audit chart usage.
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "alpine.name" . }}
+    app.kubernetes.io/name: {{ template "alpine.name" . }}
 spec:
   # This shows how to use a simple value. This will look for a passed-in value called restartPolicy.
   restartPolicy: {{ .Values.restartPolicy }}

docs/examples/nginx/templates/configmap.yaml

@@ -4,10 +4,10 @@ kind: ConfigMap
 metadata:
   name: {{ template "nginx.fullname" . }}
   labels:
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
 data:
   # When the config map is mounted as a volume, these will be created as files.
   index.html: {{ .Values.index | quote }}

docs/examples/nginx/templates/deployment.yaml

@@ -6,16 +6,16 @@ metadata:
   # multiple times into the same namespace.
   name: {{ template "nginx.fullname" . }}
   labels:
-    # The "heritage" label is used to track which tool deployed a given chart.
+    # The "app.kubernetes.io/managed-by" 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 }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    # The "release" convention makes it easy to tie a release to all of the
+    # The "app.kubernetes.io/instance" 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 }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
     # This makes it easy to audit chart usage.
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
 spec:
   replicas: {{ .Values.replicaCount }}
   template:
@@ -26,8 +26,8 @@ spec:
 {{ toYaml .Values.podAnnotations | indent 8 }}
 {{- end }}
       labels:
-        app: {{ template "nginx.name" . }}
+        app.kubernetes.io/name: {{ template "nginx.name" . }}
-        release: {{ .Release.Name }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
     spec:
       containers:
         - name: {{ template "nginx.name" . }}

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

@@ -3,16 +3,16 @@ kind: Job
 metadata:
   name: {{ template "nginx.fullname" . }}
   labels:
-    # The "heritage" label is used to track which tool deployed a given chart.
+    # The "app.kubernetes.io/managed-by" 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 }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    # The "release" convention makes it easy to tie a release to all of the
+    # The "app.kubernetes.io/instance" 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 }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
     # This makes it easy to audit chart usage.
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
   annotations:
     # This is what defines this resource as a hook. Without this line, the
     # job is considered part of the release.
@@ -22,8 +22,8 @@ spec:
     metadata:
       name: {{ template "nginx.fullname" . }}
       labels:
-        release: {{ .Release.Name }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
-        app: {{ template "nginx.name" . }}
+        app.kubernetes.io/name: {{ template "nginx.name" . }}
     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.

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

@@ -5,10 +5,10 @@ kind: Secret
 metadata:
   name: {{ template "nginx.fullname" . }}
   labels:
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.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

@@ -3,10 +3,10 @@ kind: Pod
 metadata:
   name: "{{ template "nginx.fullname" . }}-service-test"
   labels:
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
   annotations:
     "helm.sh/hook": test-success
 spec:

docs/examples/nginx/templates/service.yaml

@@ -6,10 +6,10 @@ metadata:
 {{ toYaml .Values.service.annotations | indent 4 }}
 {{- end }}
   labels:
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
-    chart: {{ .Chart.Name }}-{{ .Chart.Version }}
+    helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
   name: {{ template "nginx.fullname" . }}
 spec:
 # Provides options for the service so chart users have the full choice
@@ -35,5 +35,5 @@ spec:
       nodePort: {{ .Values.service.nodePort }}
       {{- end }}
   selector:
-    app: {{ template "nginx.name" . }}
+    app.kubernetes.io/name: {{ template "nginx.name" . }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}

pkg/chartutil/create.go

@@ -129,10 +129,10 @@ kind: Ingress
 metadata:
   name: {{ $fullName }}
   labels:
-    app: {{ include "<CHARTNAME>.name" . }}
+    app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-    chart: {{ include "<CHARTNAME>.chart" . }}
+    helm.sh/chart: {{ include "<CHARTNAME>.chart" . }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
 {{- with .Values.ingress.annotations }}
   annotations:
 {{ toYaml . | indent 4 }}
@@ -166,21 +166,21 @@ kind: Deployment
 metadata:
   name: {{ include "<CHARTNAME>.fullname" . }}
   labels:
-    app: {{ include "<CHARTNAME>.name" . }}
+    app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-    chart: {{ include "<CHARTNAME>.chart" . }}
+    helm.sh/chart: {{ include "<CHARTNAME>.chart" . }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
 spec:
   replicas: {{ .Values.replicaCount }}
   selector:
     matchLabels:
-      app: {{ include "<CHARTNAME>.name" . }}
+      app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-      release: {{ .Release.Name }}
+      app.kubernetes.io/instance: {{ .Release.Name }}
   template:
     metadata:
       labels:
-        app: {{ include "<CHARTNAME>.name" . }}
+        app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-        release: {{ .Release.Name }}
+        app.kubernetes.io/instance: {{ .Release.Name }}
     spec:
       containers:
         - name: {{ .Chart.Name }}
@@ -219,10 +219,10 @@ kind: Service
 metadata:
   name: {{ include "<CHARTNAME>.fullname" . }}
   labels:
-    app: {{ include "<CHARTNAME>.name" . }}
+    app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-    chart: {{ include "<CHARTNAME>.chart" . }}
+    helm.sh/chart: {{ include "<CHARTNAME>.chart" . }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
-    heritage: {{ .Release.Service }}
+    app.kubernetes.io/managed-by: {{ .Release.Service }}
 spec:
   type: {{ .Values.service.type }}
   ports:
@@ -231,8 +231,8 @@ spec:
       protocol: TCP
       name: http
   selector:
-    app: {{ include "<CHARTNAME>.name" . }}
+    app.kubernetes.io/name: {{ include "<CHARTNAME>.name" . }}
-    release: {{ .Release.Name }}
+    app.kubernetes.io/instancelease: {{ .Release.Name }}
 `
 
 const defaultNotes = `1. Get the application URL by running these commands:

pkg/chartutil/testdata/dependent-chart-alias/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/dependent-chart-helmignore/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/dependent-chart-no-requirements-yaml/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/dependent-chart-with-all-in-requirements-yaml/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/dependent-chart-with-mixed-requirements-yaml/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/frobnitz/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/chartutil/testdata/frobnitz_backslash/charts/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/downloader/testdata/signtest/alpine/templates/alpine-pod.yaml

@@ -3,7 +3,7 @@ kind: Pod
 metadata:
   name: {{.Release.Name}}-{{.Chart.Name}}
   labels:
-    heritage: {{.Release.Service}}
+    app.kubernetes.io/managed-by: {{.Release.Service}}
     chartName: {{.Chart.Name}}
     chartVersion: {{.Chart.Version | quote}}
   annotations:

pkg/lint/rules/testdata/albatross/templates/svc.yaml

@@ -5,9 +5,9 @@ kind: Service
 metadata:
   name: "{{ .Values.name }}"
   labels:
-    heritage: {{ .Release.Service | quote }}
+    app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
-    release: {{ .Release.Name | quote }}
+    app.kubernetes.io/instance: {{ .Release.Name | quote }}
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
     kubeVersion: {{ .Capabilities.KubeVersion.Major }}
     tillerVersion: {{ .Capabilities.TillerVersion }}
 spec: