Merge pull request #3404 from consideRatio/pr/modern-label-naming

Add recommended chart labels alongside old labels (`app.kubernetes.io/...`, `helm.sh/chart`)

Author: manics

ci/common

@@ -50,7 +50,7 @@ await_autohttps_tls_cert_acquisition() {
         kubectl logs deploy/pebble --all-containers # --prefix
         kubectl describe pod -l app.kubernetes.io/name=pebble-coredns
         kubectl logs deploy/pebble-coredns --all-containers # --prefix
-        kubectl describe pod -l component=autohttps
+        kubectl describe pod -l app.kubernetes.io/component=autohttps
         kubectl logs deploy/autohttps --all-containers # --prefix
         exit 1
     fi
@@ -72,7 +72,7 @@ await_autohttps_tls_cert_save() {
         kubectl logs deploy/pebble --all-containers # --prefix
         kubectl describe pod -l app.kubernetes.io/name=pebble-coredns
         kubectl logs deploy/pebble-coredns --all-containers # --prefix
-        kubectl describe pod -l component=autohttps
+        kubectl describe pod -l app.kubernetes.io/component=autohttps
         kubectl logs deploy/autohttps --all-containers # --prefix
         exit 1
     fi

docs/source/administrator/services.md

@@ -82,8 +82,8 @@ proxy:
         - to:
             - podSelector:
                 matchLabels:
-                  app: jupyterhub
-                  component: hub
+                  app.kubernetes.io/name: jupyterhub
+                  app.kubernetes.io/component: hub
           ports:
             - port: 8181
 ```

docs/source/resources/community.md

@@ -94,7 +94,7 @@ user pods. You can search for all user pods with the following label query:
 
 ```bash
 kubectl --namespace=<YOUR-NAMESPACE> get pod \
-    -l "component=singleuser-server"
+    -l "app.kubernetes.io/component=singleuser-server"
 ```
 
 For more information, see the [Kubernetes labels and selectors page](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).

jupyterhub/files/hub/jupyterhub_config.py

@@ -107,28 +107,35 @@ def camelCaseify(s):
 )
 
 # implement common labels
-# this duplicates the jupyterhub.commonLabels helper
+# This mimics the jupyterhub.commonLabels helper, but declares managed-by to
+# kubespawner instead of helm.
+#
+# The labels app and release are old labels enabled to be deleted in z2jh 5, but
+# for now retained to avoid a breaking change in z2jh 4 that would force user
+# server restarts. Restarts would be required because NetworkPolicy resources
+# must select old/new pods with labels that then needs to be seen on both
+# old/new pods, and we want these resources to keep functioning for old/new user
+# server pods during an upgrade.
+#
 common_labels = c.KubeSpawner.common_labels = {}
-common_labels["app"] = get_config(
+common_labels["app.kubernetes.io/name"] = common_labels["app"] = get_config(
     "nameOverride",
     default=get_config("Chart.Name", "jupyterhub"),
 )
-common_labels["heritage"] = "jupyterhub"
+release = get_config("Release.Name")
+if release:
+    common_labels["app.kubernetes.io/instance"] = common_labels["release"] = release
 chart_name = get_config("Chart.Name")
 chart_version = get_config("Chart.Version")
 if chart_name and chart_version:
-    common_labels["chart"] = "{}-{}".format(
-        chart_name,
-        chart_version.replace("+", "_"),
+    common_labels["helm.sh/chart"] = common_labels["chart"] = (
+        f"{chart_name}-{chart_version.replace('+', '_')}"
     )
-release = get_config("Release.Name")
-if release:
-    common_labels["release"] = release
+common_labels["app.kubernetes.io/managed-by"] = "kubespawner"
 
 c.KubeSpawner.namespace = os.environ.get("POD_NAMESPACE", "default")
 
 # Max number of consecutive failures before the Hub restarts itself
-# requires jupyterhub 0.9.2
 set_config_if_not_none(
     c.Spawner,
     "consecutive_failure_limit",

jupyterhub/templates/_helpers.tpl

@@ -48,7 +48,6 @@
   - commonLabels      | uses appLabel
   - labels            | uses commonLabels
   - matchLabels       | uses labels
-  - podCullerSelector | uses matchLabels
 
 
   ## Example usage
@@ -112,31 +111,62 @@
 {{- /*
   jupyterhub.commonLabels:
     Foundation for "jupyterhub.labels".
-    Provides labels: app, release, (chart and heritage).
+
+    Provides old labels:
+      app
+      release
+      chart (omitted for matchLabels)
+      heritage (omitted for matchLabels)
+    Provides modern labels (omitted for matchLabels):
+      app.kubernetes.io/name ("app")
+      app.kubernetes.io/instance ("release")
+      helm.sh/chart ("chart")
+      app.kubernetes.io/managed-by ("heritage")
 */}}
 {{- define "jupyterhub.commonLabels" -}}
-app: {{ .appLabel | default (include "jupyterhub.appLabel" .) }}
-release: {{ .Release.Name }}
+app: {{ .appLabel | default (include "jupyterhub.appLabel" .) | quote }}
+release: {{ .Release.Name | quote }}
 {{- if not .matchLabels }}
 chart: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
-heritage: {{ .heritageLabel | default .Release.Service }}
+heritage: {{ .Release.Service }}
+app.kubernetes.io/name: {{ .appLabel | default (include "jupyterhub.appLabel" .) | quote }}
+app.kubernetes.io/instance: {{ .Release.Name | quote }}
+helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
 {{- end }}
 {{- end }}
 
 
 {{- /*
   jupyterhub.labels:
-    Provides labels: component, app, release, (chart and heritage).
+    Provides old labels:
+      component
+      app
+      release
+      chart (omitted for matchLabels)
+      heritage (omitted for matchLabels)
+    Provides modern labels (omitted for matchLabels):
+      app.kubernetes.io/component ("component")
+      app.kubernetes.io/name ("app")
+      app.kubernetes.io/instance release ("release")
+      helm.sh/chart ("chart")
+      app.kubernetes.io/managed-by ("heritage")
 */}}
 {{- define "jupyterhub.labels" -}}
 component: {{ include "jupyterhub.componentLabel" . }}
+{{- if not .matchLabels }}
+app.kubernetes.io/component: {{ include "jupyterhub.componentLabel" . }}
+{{- end }}
 {{ include "jupyterhub.commonLabels" . }}
 {{- end }}
 
 
 {{- /*
   jupyterhub.matchLabels:
-    Used to provide pod selection labels: component, app, release.
+    Provides old labels:
+      component
+      app
+      release
 */}}
 {{- define "jupyterhub.matchLabels" -}}
 {{- $_ := merge (dict "matchLabels" true) . -}}

jupyterhub/templates/hub/secret.yaml

@@ -8,7 +8,7 @@ type: Opaque
 data:
   {{- $values := merge dict .Values }}
   {{- /* also passthrough subset of Chart / Release */}}
-  {{- $_ := set $values "Chart" (dict "Name" .Chart.Name "Version" .Chart.Version) }}
+  {{- $_ := set $values "Chart" (dict "Name" .Chart.Name "Version" .Chart.Version "AppVersion" .Chart.AppVersion) }}
   {{- $_ := set $values "Release" (pick .Release "Name" "Namespace" "Service") }}
   values.yaml: {{ $values | toYaml | b64enc | quote }}
 

jupyterhub/templates/proxy/autohttps/deployment.yaml

@@ -130,10 +130,10 @@ spec:
           {{- end }}
           args:
             - watch-save
-            - --label=app={{ include "jupyterhub.appLabel" . }}
-            - --label=release={{ .Release.Name }}
-            - --label=chart={{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
-            - --label=heritage=secret-sync
+            - --label=app.kubernetes.io/name={{ include "jupyterhub.appLabel" . }}
+            - --label=app.kubernetes.io/instance={{ .Release.Name }}
+            - --label=helm.sh/chart={{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}
+            - --label=app.kubernetes.io/managed-by=secret-sync
             - {{ include "jupyterhub.proxy-public-tls.fullname" . }}
             - acme.json
             - /etc/acme/acme.json

jupyterhub/values.schema.yaml

@@ -625,7 +625,7 @@ properties:
                     - to:
                         - podSelector:
                             matchLabels:
-                              app: my-k8s-local-service
+                              app.kubernetes.io/name: my-k8s-local-service
                       ports:
                         - protocol: TCP
                           port: 5978

tests/test_spawn.py

@@ -1,3 +1,4 @@
+import json
 import subprocess
 import time
 
@@ -22,7 +23,7 @@ def test_spawn_basic(
     r = api_request.post("/users/" + jupyter_user + "/server")
     assert r.status_code in (201, 202)
     try:
-        # check successfull spawn
+        # check successful spawn
         server_model = _wait_for_user_to_spawn(
             api_request, jupyter_user, request_data["test_timeout"]
         )
@@ -36,8 +37,37 @@ def test_spawn_basic(
         assert r.status_code == 200
         assert "version" in r.json()
 
-        # check user pod's extra environment variable
         pod_name = server_model["state"]["pod_name"]
+
+        # check user pod's labels
+        pod_json = subprocess.check_output(
+            [
+                "kubectl",
+                "get",
+                "pod",
+                "--output=json",
+                pod_name,
+            ]
+        )
+        pod = json.loads(pod_json)
+        pod_labels = pod["metadata"]["labels"]
+
+        # check for modern labels
+        assert pod_labels["app.kubernetes.io/name"] == "jupyterhub"
+        assert "app.kubernetes.io/instance" in pod_labels
+        # FIXME: app.kubernetes.io/component for user pods require kubespawner
+        #        with https://github.com/jupyterhub/kubespawner/pull/835.
+        # assert pod_labels["app.kubernetes.io/component"] == "singleuser-server"
+        assert pod_labels["helm.sh/chart"].startswith("jupyterhub-")
+        assert pod_labels["app.kubernetes.io/managed-by"] == "kubespawner"
+
+        # check for legacy labels still meant to be around
+        assert pod_labels["app"] == "jupyterhub"
+        assert "release" in pod_labels
+        assert pod_labels["chart"].startswith("jupyterhub-")
+        assert pod_labels["component"] == "singleuser-server"
+
+        # check user pod's extra environment variable
         c = subprocess.run(
             [
                 "kubectl",

tools/templates/lint-and-validate-values.yaml

@@ -186,7 +186,7 @@ hub:
       - to:
           - podSelector:
               matchLabels:
-                app: my-k8s-local-service
+                app.kubernetes.io/name: my-k8s-local-service
         ports:
           - protocol: TCP
             port: 5978