DEV Community: gre9ory

HULL Tutorial 08: Wrapping up with a Summary and Analysis

gre9ory — Tue, 31 May 2022 11:25:52 +0000

Summary

To finish this tutorial let's do some comparisons. For this copy over once more the last chart state which is also the final one and make the values.full.yaml the values.yaml:

cd ~/kubernetes-dashboard-hull && cp -R 07_advanced_configuration/ 08_summary && cd 08_summary/kubernetes-dashboard-hull && rm values.yaml && cp values.full.yaml values.yaml

And here is the final values.yaml:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      externalPort: 443
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}
  objects:
    servicemonitor:
      dashboard:
        enabled: false
        endpoints: |-
          _HT![
            {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
            { port: "http" }
            {{ else }}
            { port: "https" }
            {{ end }}
          ]
        selector:
          matchLabels: _HT&dashboard
    networkpolicy:
      dashboard:
        enabled: false
        labels:
          app: _HT!{{- default (index . "$").Chart.Name (index . "$").Values.nameOverride | trunc 63 | trimSuffix "-" -}}
          chart: _HT!{{- printf "%s-%s" (index . "$").Chart.Name (index . "$").Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
          release: _HT!{{ (index . "$").Release.Name }}
          heritage: _HT!{{ (index . "$").Release.Service }}
        podSelector:
          matchLabels: _HT&dashboard
        ingress: |-
          _HT![
            { ports:
              [
                {
                  protocol: TCP,
                  {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
                  port: "http"
                  {{ else }}
                  port: "https"
                  {{ end }}
                }
              ]
            }
          ]
    poddisruptionbudget:
      dashboard:
        enabled: false
        selector:
          matchLabels: _HT&dashboard
    podsecuritypolicy:
      dashboard:
        enabled: false
        annotations:
          seccomp.security.alpha.kubernetes.io/allowedProfileNames: "*"
        privileged: false
        fsGroup:
          rule: RunAsAny
        runAsUser:
          rule: RunAsAny
        runAsGroup:
          rule: RunAsAny
        seLinux:
          rule: RunAsAny
        supplementalGroups:
          rule: RunAsAny
        volumes:
        - configMap
        - secret
        - emptyDir
        allowPrivilegeEscalation: false
        hostNetwork: false
        hostIPC: false
        hostPID: false
    rolebinding:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: _HT^psp
        subjects:
        - kind: ServiceAccount
          namespace: _HT!{{ (index . "$").Release.Namespace }}
          name: _HT^default
    service:
      dashboard:
        labels:
          ## Enable or disable the kubernetes.io/cluster-service label. Should be disabled for GKE clusters >=1.15.
          ## Otherwise, the addon manager will presume ownership of the service and try to delete it.
          "kubernetes.io/cluster-service": "true"
        type: ClusterIP
        ports:
          http:
            enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
            port: _HT*hull.config.specific.externalPort
            targetPort: http
          https:
            enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
            port: _HT*hull.config.specific.externalPort
            targetPort: https
    ingress:
      dashboard:
        enabled: false
        annotations: |-
          _HT!{
            {{ if not (index . "$").Values.hull.config.specific.protocolHttp }}
            "nginx.ingress.kubernetes.io/backend-protocol": "HTTPS",
            "service.alpha.kubernetes.io/app-protocols": "{\"https\":\"HTTPS\"}"
            {{ end }}
          }
        rules:
          default:
            http:
              paths:
                root:
                  path: /
                  pathType: ImplementationSpecific
                  backend:
                    service:
                      name: dashboard
                      port:
                        number: _HT*hull.config.specific.externalPort
    deployment:
      dashboard:
        enabled: true
        replicas: 1
        strategy:
          rollingUpdate:
            maxSurge: 0
            maxUnavailable: 1
          type: RollingUpdate
        pod:
          securityContext:
            seccompProfile:
              type: RuntimeDefault
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: v2.5.0
              imagePullPolicy: IfNotPresent
              args: _HT![
                  {{- $p := (index . "$") }}
                  "--namespace={{ $p.Release.Namespace }}",
                  {{- if not $p.Values.hull.config.specific.protocolHttp }}
                  "--auto-generate-certificates",
                  {{- end }}
                  {{- if $p.Values.hull.objects.deployment.dashboard.pod.containers.metricsscraper.enabled }}
                  "--sidecar-host=http://127.0.0.1:8000",
                  {{- else }}
                  "--metrics-provider=none",
                  {{- end }}
                  ]
              ports:
                http:
                  enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
                  containerPort: 9090
                  protocol: TCP
                https:
                  enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
                  containerPort: 8443
                  protocol: TCP
              volumeMounts:
                dashboard:
                  name: kubernetes-dashboard-certs
                  mountPath: /certs
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              livenessProbe: |-
                _HT!{
                  httpGet: {
                    path: /,
                    scheme: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary "HTTP" "HTTPS" }},
                    port: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary 9090 8443 }}
                    }
                  }
                initialDelaySeconds: 30
                timeoutSeconds: 30
              resources:
                requests:
                  cpu: 100m
                  memory: 200Mi
                limits:
                  cpu: 2
                  memory: 200Mi
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
            metricsscraper:
              enabled: false
              image:
                repository: kubernetesui/metrics-scraper
                tag: v1.0.7
              imagePullPolicy: IfNotPresent
              ports:
                tcp:
                  containerPort: 8000
                  protocol: TCP
              livenessProbe:
                httpGet:
                  scheme: HTTP
                  path: /
                  port: 8000
                initialDelaySeconds: 30
                timeoutSeconds: 30
              volumeMounts:
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
          volumes:
            kubernetes-dashboard-certs:
              secret:
                secretName: certs
            tmp-volume:
              emptyDir: {}
    role:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        rules:
          psp:
            apiGroups:
            - extensions
            - policy/v1beta1
            resources:
            - podsecuritypolicies
            verbs:
            - use
            resourceNames: _HT![ {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "psp") }} ]
      default:
        rules:
          secrets:
            apiGroups:
            - ""
            resources:
            - secrets
            resourceNames: _HT![
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "certs") }},
              "kubernetes-dashboard-csrf",
              "kubernetes-dashboard-key-holder"
              ]
            verbs:
            - get
            - update
            - delete
          configmaps:
            apiGroups:
            - ""
            resources:
            - configmaps
            resourceNames: _HT![
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "settings") }} ]
            verbs:
            - get
            - update
          services:
            apiGroups:
            - ""
            resources:
            - services
            resourceNames:
            - "heapster"
            - "dashboard-metrics-scraper"
            verbs:
            - proxy
          services_proxy:
            apiGroups:
            - ""
            resources:
            - services/proxy
            resourceNames:
            - "heapster"
            - "http:heapster:"
            - "https:heapster:"
            - "dashboard-metrics-scraper"
            - "http:dashboard-metrics-scraper"
            verbs:
            - get
    clusterrole:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        rules:
          cluster_objects:
            apiGroups:
            - ""
            resources:
            - configmaps
            - endpoints
            - persistentvolumeclaims
            - pods
            - replicationcontrollers
            - replicationcontrollers/scale
            - serviceaccounts
            - services
            - nodes
            - persistentvolumeclaims
            - persistentvolumes
            verbs:
            - get
            - list
            - watch
          statuses:
            apiGroups:
            - ""
            resources:
            - bindings
            - events
            - limitranges
            - namespaces/status
            - pods/log
            - pods/status
            - replicationcontrollers/status
            - resourcequotas
            - resourcequotas/status
            verbs:
            - get
            - list
            - watch
          namespaces:
            apiGroups:
            - ""
            resources:
            - namespaces
            verbs:
            - get
            - list
            - watch
          apps:
            apiGroups:
            - apps
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - replicasets
            - replicasets/scale
            - statefulsets
            verbs:
            - get
            - list
            - watch
          autoscaling:
            apiGroups:
            - autoscaling
            resources:
            - horizontalpodautoscalers
            verbs:
            - get
            - list
            - watch
          jobs:
            apiGroups:
            - batch
            resources:
            - cronjobs
            - jobs
            verbs:
            - get
            - list
            - watch
          extensions:
            apiGroups:
            - extensions
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - ingresses
            - networkpolicies
            - replicasets
            - replicasets/scale
            - replicationcontrollers/scale
            verbs:
            - get
            - list
            - watch
          pdb:
            apiGroups:
            - policy
            resources:
            - poddisruptionbudgets
            verbs:
            - get
            - list
            - watch
          network:
            apiGroups:
            - networking.k8s.io
            resources:
            - networkpolicies
            - ingresses
            verbs:
            - get
            - list
            - watch
          storage:
            apiGroups:
            - storage.k8s.io
            resources:
            - storageclasses
            - volumeattachments
            verbs:
            - get
            - list
            - watch
          rbac:
            apiGroups:
            - rbac.authorization.k8s.io
            resources:
            - clusterrolebindings
            - clusterroles
            - roles
            - rolebindings
            verbs:
            - get
            - list
            - watch
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        rules:
          metrics:
            apiGroups:
            - "metrics.k8s.io"
            resources:
            - pods
            - nodes
            verbs:
            - get
            - list
            - watch
    clusterrolebinding:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^readonly
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^metrics
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default
    configmap:
      settings:
        data:
          _global:
            inline: _HT!{{ toJson (index . "$").Values.hull.config.specific.settings | quote }}
          _pinnedCRD:
            path: files/pinnedCRDs
    secret:
      certs:
        data: {}
      kubernetes-dashboard-csrf:
        data: {}
        staticName: true
      kubernetes-dashboard-key-holder:
        data: {}
        staticName: true

It could do with some sorting of object types and brushing up with lots of comments and documentation. The effort not spend on template creation should be put into writing good and extensive documentation of the values.yaml - only for reasons of keeping everything shorter no comments were added in this tutorial.

Let's render it finally with everything included:

helm template .

and here it is - the default configuration of kubernetes-dashboard-hull:

# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: certs
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-certs
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-csrf
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: kubernetes-dashboard-csrf
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-key-holder
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: kubernetes-dashboard-key-holder
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: '{}'
  _pinnedCRD: '{}'
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: metrics
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-metrics
  namespace: ""
rules:
- apiGroups:
  - metrics.k8s.io
  resources:
  - pods
  - nodes
  verbs:
  - get
  - list
  - watch
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: metrics
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-metrics
  namespace: ""
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: release-name-kubernetes-dashboard-metrics
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
  namespace: default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules:
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-settings
  resources:
  - configmaps
  verbs:
  - get
  - update
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-certs
  - kubernetes-dashboard-csrf
  - kubernetes-dashboard-key-holder
  resources:
  - secrets
  verbs:
  - get
  - update
  - delete
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - dashboard-metrics-scraper
  resources:
  - services
  verbs:
  - proxy
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - 'http:heapster:'
  - 'https:heapster:'
  - dashboard-metrics-scraper
  - http:dashboard-metrics-scraper
  resources:
  - services/proxy
  verbs:
  - get
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Service
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    kubernetes.io/cluster-service: "true"
  name: release-name-kubernetes-dashboard-dashboard
spec:
  ports:
  - name: https
    port: 443
    targetPort: https
  selector:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/name: kubernetes-dashboard
  type: ClusterIP
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - args:
        - --namespace=default
        - --auto-generate-certificates
        - --metrics-provider=none
        env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        imagePullPolicy: IfNotPresent
        livenessProbe:
          httpGet:
            path: /
            port: 8443
            scheme: HTTPS
        name: dashboard
        ports:
        - containerPort: 8443
          name: https
          protocol: TCP
        resources:
          limits:
            cpu: 2
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsGroup: 2001
          runAsUser: 1001
        volumeMounts:
        - mountPath: /certs
          name: kubernetes-dashboard-certs
        - mountPath: /tmp
          name: tmp-volume
      imagePullSecrets: []
      initContainers: []
      securityContext:
        seccompProfile:
          type: RuntimeDefault
      serviceAccountName: release-name-kubernetes-dashboard-default
      volumes:
      - name: kubernetes-dashboard-certs
        secret:
          secretName: release-name-kubernetes-dashboard-certs
      - emptyDir: {}
        name: tmp-volume

Lines of Code

Assuming you have created that functionally resembles the original kubernetes-dashboard Helm chart, let's consider some numbers.

Here is a Lines of Code analysis performed with the Visual Studio Code LoC Extension for the original kubernetes-dashboard charts relevant configuration files (values.yaml + templates):

File	Lines of Code	Comments
`values.yaml`	149	161
`templates/_helpers.tpl`	64	15
`templates/_tplvalues.tpl`	23	5
`templates/clusterrole-metrics.yaml`	33	1
`templates/clusterrole-readonly.yaml`	153	1
`templates/clusterrolebinding-metrics.yaml`	36	1
`templates/clusterrolebinding-readonly.yaml`	36	1
`templates/configmap.yaml`	33	1
`templates/deployment.yaml`	186	2
`templates/ingress.yaml`	88	1
`templates/networkpolicy.yaml`	44	1
`templates/pdb.yaml`	38	1
`templates/psp.yaml`	81	1
`templates/role.yaml`	48	1
`templates/rolebinding.yaml`	36	1
`templates/secret.yaml`	46	1
`templates/service.yaml`	58	1
`templates/serviceaccount.yaml`	28	1
`templates/servicemonitor.yaml`	40	1
Total	1220	198

Essentially there exist ~1220 lines of configurational code written which need to be maintained by the chart maintainers. The chart consumers need to understand and maintain ~150 lines of configuration in the values.yaml but will likely need to check the templates too to understand the inner workings.

Compared to that, the kubernetes-dashboard-hull's values.yaml - containing all configuration code - consists of a mere 460 lines of configuration. With only about a third of the original configuration code to maintain, the HULL based chart arguably covers the default structure and logic of the source chart. But still it is relatively unrestricted in the ways you can adapt the configuration to your needs in any given deployment scenario.

Thank you for staying with us and hope you enjoyed the turorial :)

HULL Tutorial 07: Configuring Advanced Objects

gre9ory — Tue, 31 May 2022 11:25:35 +0000

Preparation

In this tutorial section you are going to deal with the remaining template files and a little more advanced things you can tweak in the kubernetes-dashboard chart which we haven't covered yet. This will conclude the educational conversion of objects from a 'regular' Helm chart to a HULL based chart.

But before diving into this prepare your working folder again and copy over the last sections result:

cd ~/kubernetes-dashboard-hull && cp -R 06_service_api/ 07_advanced_configuration && cd 07_advanced_configuration/kubernetes-dashboard-hull

Prepare the values.yaml:

sed '/  objects:/Q' values.full.yaml > values.yaml

and once more verify the result:

cat values.yaml

currently looks like:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      externalPort: 443
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}

For a reminder of the source template check the templates folder again:

ls ../kubernetes-dashboard/templates

showing the following files:

NOTES.txt       clusterrole-metrics.yaml         clusterrolebinding-readonly.yaml  ingress.yaml        psp.yaml          secret.yaml          servicemonitor.yaml
_helpers.tpl    clusterrole-readonly.yaml        configmap.yaml                    networkpolicy.yaml  role.yaml         service.yaml
_tplvalues.tpl  clusterrolebinding-metrics.yaml  deployment.yaml                   pdb.yaml            rolebinding.yaml  serviceaccount.yaml

Most of them are covered by now, the remaining ones and subject of this tutorial section are:

networkpolicy.yaml
pdb.yaml
psp.yaml
servicemonitor.yaml

Aspects such as NetworkPolicies, PodDisruptionBudgets, PodSecurityPolicies and ServiceMonitors can be considered more advanced use vases as you can see that you need to enable each of these features explicitly to use them in the kubernetes-dashboard chart.

Using in-built ServiceMonitors and CRDs

The ServiceMonitor concept is part of the Prometheus Operator concept and offers a convenient way to add and remove endpoints which export Prometheus metrics so a Prometheus instance can dynamically monitor them.

Since it is a very popular concept to expose an applications metric, the ServiceMonitor has its own object type servicemonitor in the HULL world.

By default the ServiceMonitor in values.yaml:

cat ../kubernetes-dashboard/values.yaml | grep "^serviceMonitor:" -B 1 -A 2

is disabled:


serviceMonitor:
  # Whether or not to create a Prometheus Operator service monitor.
  enabled: false

Here you can create the servicemonitor object according to its underlying logic:

echo '  objects:
    servicemonitor:
      dashboard:
        enabled: false
        endpoints: |-
          _HT![ 
            {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
            { port: "http" }
            {{ else }}
            { port: "https" }
            {{ end }}
          ]
        selector:
          matchLabels: _HT&dashboard' >> values.yaml

Enable the ServiceMonitor with this:

echo 'hull:
  objects:
    servicemonitor:
      dashboard:
        enabled: true' > ../configs/servicemonitor.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/servicemonitor.yaml .

and test the output:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  endpoints:
  - port: https
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard

If there are any other CustomResourceDefinitions or CustomResources to create within your Helm chart this is possible too in HULL by:

the ability to deploy your CRDs with the crds folder
the ability to specify any CustomResource as a customresource object instance. For CustomResources you additionally need to specify the kind and apiVersion besides the free form spec of your object.

Specifying NetworkPolicies

The networkpolicy.yaml:

cat ../kubernetes-dashboard/templates/networkpolicy.yaml

is pretty lightweight:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.networkPolicy.enabled -}}
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  labels:
    app: {{ template "kubernetes-dashboard.name" . }}
    chart: {{ template "kubernetes-dashboard.chart" . }}
    release: {{ .Release.Name }}
    heritage: {{ .Release.Service }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
spec:
  podSelector:
    matchLabels:
{{ include "kubernetes-dashboard.matchLabels" . | nindent 6 }}
  ingress:
  - ports:
{{- if .Values.protocolHttp }}
    - port: http
      protocol: TCP
{{- else }}
    - port: https
      protocol: TCP
{{- end -}}
{{- end -}}

and disabled by default as shown:

cat ../kubernetes-dashboard/values.yaml | grep "^networkPolicy:" -B 1 -A 3

in the values.yaml:


networkPolicy:
  # Whether to create a network policy that allows/restricts access to the service
  enabled: false

The addition of the new fixed labels here:

  labels:
    app: {{ template "kubernetes-dashboard.name" . }}
    chart: {{ template "kubernetes-dashboard.chart" . }}
    release: {{ .Release.Name }}
    heritage: {{ .Release.Service }}

appears to be pretty much out of line with the metadata handling of the other objects in this chart and may likely not have a functionality even. Anyway for completeness sake add them to the new objects metadata labels by transporting the underlying logic.

Regarding the podSelector you can utilize HULL's hull.tranformation.selector function to create the corresponding labels to match the dashboard pods.

That's all, write it to the values.yaml:

echo '    networkpolicy:
      dashboard:
        enabled: false
        labels:
          app: _HT!{{- default (index . "$").Chart.Name (index . "$").Values.nameOverride | trunc 63 | trimSuffix "-" -}}
          chart: _HT!{{- printf "%s-%s" (index . "$").Chart.Name (index . "$").Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
          release: _HT!{{ (index . "$").Release.Name }}
          heritage: _HT!{{ (index . "$").Release.Service }}
        podSelector:
          matchLabels: _HT&dashboard
        ingress: |-
          _HT![
            { ports:
              [
                {
                  protocol: TCP,
                  {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
                  port: "http"
                  {{ else }}
                  port: "https"
                  {{ end }}
                }
              ]
            }
          ]'>> values.yaml

and apply the helm template command on the enabled networkpolicy:

echo 'hull:
  objects:
    networkpolicy:
      dashboard:
        enabled: true' > ../configs/networkpolicy.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/networkpolicy.yaml .

and verify the results correctness:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  annotations: {}
  labels:
    app: kubernetes-dashboard
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    chart: kubernetes-dashboard-5.2.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    heritage: Helm
    release: release-name
  name: release-name-kubernetes-dashboard-dashboard
spec:
  ingress:
  - ports:
    - port: https
      protocol: TCP
  podSelector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard

Specifying a PodDisruptionBudget

PodDisruptionBudgets have three fields:

A label selector .spec.selector to specify the set of pods to which it applies. This field is required.
.spec.minAvailable which is a description of the number of pods from that set that must still be available after the eviction, even in the absence of the evicted pod. minAvailable can be either an absolute number or a percentage.
.spec.maxUnavailable (available in Kubernetes 1.7 and higher) which is a description of the number of pods from that set that can be unavailable after the eviction. It can be either an absolute number or a percentage.

Take a look at our PodDisruptionBudget definition:

cat ../kubernetes-dashboard/templates/pdb.yaml

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.podDisruptionBudget.enabled -}}
apiVersion: policy/v1beta1
kind: PodDisruptionBudget
metadata:
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
  name: {{ template "kubernetes-dashboard.fullname" . }}
spec:
  {{- if .Values.podDisruptionBudget.minAvailable }}
  minAvailable: {{ .Values.podDisruptionBudget.minAvailable }}
  {{- end  }}
  {{- if .Values.podDisruptionBudget.maxUnavailable }}
  maxUnavailable: {{ .Values.podDisruptionBudget.maxUnavailable }}
  {{- end  }}
  selector:
    matchLabels:
{{ include "kubernetes-dashboard.matchLabels" . | nindent 6 }}
{{- end -}}

In the values.yaml:

cat ../kubernetes-dashboard/values.yaml | grep "^podDisruptionBudget:" -B 3 -A 6

default values are omitted for minAvailable and maxUnavailable:


## podDisruptionBudget
## ref: https://kubernetes.io/docs/tasks/run-application/configure-pdb/
podDisruptionBudget:
  enabled: false
  ## Minimum available instances; ignored if there is no PodDisruptionBudget
  minAvailable:
  ## Maximum unavailable instances; ignored if there is no PodDisruptionBudget
  maxUnavailable:

Again you can put the handy _HT& selector transformation to good use here and specify the object template:

echo '    poddisruptionbudget:
      dashboard:
        enabled: false
        selector:
          matchLabels: _HT&dashboard' >> values.yaml

and again do a quick check by enabling the PodDisruptionBudget:

echo 'hull:
  objects:
    poddisruptionbudget:
      dashboard:
        enabled: true' > ../configs/pdb.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/pdb.yaml .

which is pretty bare bones:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard

Setting up PodSecurityPolicies

When you inspect the remaining PodSecurityPolicy file:

cat ../kubernetes-dashboard/templates/psp.yaml

you find a PodSecurityPolicy and - surprisingly - another Role and RoleBinding:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.podSecurityPolicy.enabled -}}
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}-psp
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
spec:
  privileged: false
  fsGroup:
    rule: RunAsAny
  runAsUser:
    rule: RunAsAny
  runAsGroup:
    rule: RunAsAny
  seLinux:
    rule: RunAsAny
  supplementalGroups:
    rule: RunAsAny
  volumes:
    - 'configMap'
    - 'secret'
    - 'emptyDir'
  allowPrivilegeEscalation: false
  hostNetwork: false
  hostIPC: false
  hostPID: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}-psp
  labels:
{{ include "kubernetes-dashboard.labels" . | nindent 4 }}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: {{ template "kubernetes-dashboard.fullname" . }}-psp
subjects:
- kind: ServiceAccount
  name: {{ template "kubernetes-dashboard.serviceAccountName" . }}
  namespace: {{ .Release.Namespace }}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}-psp
  labels:
{{ include "kubernetes-dashboard.labels" . | nindent 4 }}
rules:
- apiGroups:
  - extensions
  - policy/v1beta1
  resources:
  - podsecuritypolicies
  verbs:
  - use
  resourceNames:
  - {{ template "kubernetes-dashboard.fullname" . }}-psp
{{- end -}}

The values.yaml

cat ../kubernetes-dashboard/values.yaml | grep "^podSecurityPolicy:" -B 2 -A 3

offers the following content on podSecurityPolicy:


## podSecurityPolicy for fine-grained authorization of pod creation and updates
podSecurityPolicy:
  # Specifies whether a pod security policy should be created
  enabled: false

Apart from the surprise of the unexpected objects there is nothing new to be found here and we can straight up convert them by adding the PodSecurityPolicy, the Role and RoleBinding:

echo '    podsecuritypolicy:
      dashboard:
        enabled: false
        annotations:
          seccomp.security.alpha.kubernetes.io/allowedProfileNames: "*"
        privileged: false
        fsGroup:
          rule: RunAsAny
        runAsUser:
          rule: RunAsAny
        runAsGroup:
          rule: RunAsAny
        seLinux:
          rule: RunAsAny
        supplementalGroups:
          rule: RunAsAny
        volumes:
        - configMap
        - secret
        - emptyDir
        allowPrivilegeEscalation: false
        hostNetwork: false
        hostIPC: false
        hostPID: false
    rolebinding:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: _HT^psp
        subjects:
        - kind: ServiceAccount
          namespace: _HT!{{ (index . "$").Release.Namespace }}
          name: _HT^default
    role:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        rules:
          psp:
            apiGroups:
            - extensions
            - policy/v1beta1
            resources:
            - podsecuritypolicies
            verbs:
            - use
            resourceNames: _HT![ {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "psp") }} ]' >> values.yaml

Enable the PSP with this:

echo 'hull:
  objects:
    podsecuritypolicy:
      dashboard:
        enabled: true' > ../configs/psp.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/psp.yaml .

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: policy/v1beta1
kind: PodSecurityPolicy
metadata:
  annotations:
    seccomp.security.alpha.kubernetes.io/allowedProfileNames: '*'
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  allowPrivilegeEscalation: false
  fsGroup:
    rule: RunAsAny
  hostIPC: false
  hostNetwork: false
  hostPID: false
  privileged: false
  runAsGroup:
    rule: RunAsAny
  runAsUser:
    rule: RunAsAny
  seLinux:
    rule: RunAsAny
  supplementalGroups:
    rule: RunAsAny
  volumes:
  - configMap
  - secret
  - emptyDir
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: psp
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-psp
rules:
- apiGroups:
  - extensions
  - policy/v1beta1
  resourceNames:
  - release-name-kubernetes-dashboard-psp
  resources:
  - podsecuritypolicies
  verbs:
  - use
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: psp
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-psp
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-psp
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
  namespace: default

Wrap Up

The object conversion is done, time to clean up once more.

Your values.yaml should resemble this now:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      externalPort: 443
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}
  objects:
    servicemonitor:
      dashboard:
        enabled: false
        endpoints: |-
          _HT![
            {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
            { port: "http" }
            {{ else }}
            { port: "https" }
            {{ end }}
          ]
        selector:
          matchLabels: _HT&dashboard
    networkpolicy:
      dashboard:
        enabled: false
        labels:
          app: _HT!{{- default (index . "$").Chart.Name (index . "$").Values.nameOverride | trunc 63 | trimSuffix "-" -}}
          chart: _HT!{{- printf "%s-%s" (index . "$").Chart.Name (index . "$").Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
          release: _HT!{{ (index . "$").Release.Name }}
          heritage: _HT!{{ (index . "$").Release.Service }}
        podSelector:
          matchLabels: _HT&dashboard
        ingress: |-
          _HT![
            { ports:
              [
                {
                  protocol: TCP,
                  {{ if (index . "$").Values.hull.config.specific.protocolHttp }}
                  port: "http"
                  {{ else }}
                  port: "https"
                  {{ end }}
                }
              ]
            }
          ]
    poddisruptionbudget:
      dashboard:
        enabled: false
        selector:
          matchLabels: _HT&dashboard
    podsecuritypolicy:
      dashboard:
        enabled: false
        annotations:
          seccomp.security.alpha.kubernetes.io/allowedProfileNames: "*"
        privileged: false
        fsGroup:
          rule: RunAsAny
        runAsUser:
          rule: RunAsAny
        runAsGroup:
          rule: RunAsAny
        seLinux:
          rule: RunAsAny
        supplementalGroups:
          rule: RunAsAny
        volumes:
        - configMap
        - secret
        - emptyDir
        allowPrivilegeEscalation: false
        hostNetwork: false
        hostIPC: false
        hostPID: false
    rolebinding:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: _HT^psp
        subjects:
        - kind: ServiceAccount
          namespace: _HT!{{ (index . "$").Release.Namespace }}
          name: _HT^default
    role:
      psp:
        enabled: _HT?(index . "$").Values.hull.objects.podsecuritypolicy.dashboard.enabled
        rules:
          psp:
            apiGroups:
            - extensions
            - policy/v1beta1
            resources:
            - podsecuritypolicies
            verbs:
            - use
            resourceNames: _HT![ {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "psp") }} ]

Backup what you did in this tutorial part:

cp values.yaml values.tutorial-part.yaml

Since there exists a role block now in the current values.full.yaml and our local values.yaml it is required to merge them appropriately. Otherwise the second role key will overwrite the first which is not helpful. To create the final values.full.yaml you hence need to do a little more work but you can just copy and paste the following 'one liner' and it should do:

sed '1,/objects:/d' values.full.yaml > _tmp \
&& sed '/^\s\s\s\srole:/r'<(
  echo "      psp:"
  echo "        enabled: _HT?(index . \"$\").Values.hull.objects.podsecuritypolicy.dashboard.enabled"
  echo "        rules:"
  echo "          psp:"
  echo "            apiGroups:"
  echo "            - extensions"
  echo "            - policy/v1beta1"
  echo "            resources:"
  echo "            - podsecuritypolicies"
  echo "            verbs:"
  echo "            - use"
  echo '            resourceNames: _HT![ {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "psp") }} ]'
) -i -- _tmp \
&& cp values.yaml values.full.yaml \
&& sed '/^\s\s\s\srole:/,$d' -i values.full.yaml \
&& cat _tmp >> values.full.yaml \
&& rm _tmp

Thanks again, only the wrap up of everything and summary left in this tutorial series.

HULL Tutorial 06: Writing Services and Ingresses

gre9ory — Tue, 31 May 2022 11:25:23 +0000

Preparation

Next up is a closer look at the objects from the Kubernetes Service API which includes Services, Ingresses and Endpoints.

But as before copy over our working chart from the last tutorial part to a new folder:

cd ~/kubernetes-dashboard-hull && cp -R 05_workloads/ 06_service_api && cd 06_service_api/kubernetes-dashboard-hull

To remove the HULL hull.objects from values.full.yaml and prepare our testing values.yaml enter:

sed '/  objects:/Q' values.full.yaml > values.yaml

and verify the result:

cat values.yaml

looks like:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}

Check for existing Service API objects

Start the investigation as you did before:

find ../kubernetes-dashboard/templates -type f -iregex '.*\(Service\|\Ingress\|\Endpoint\).*' | sort

which returns:

../kubernetes-dashboard/templates/ingress.yaml
../kubernetes-dashboard/templates/service.yaml
../kubernetes-dashboard/templates/serviceaccount.yaml
../kubernetes-dashboard/templates/servicemonitor.yaml

Ignoring the ServiceAccount (already handled) and the ServiceMonitor (handled later) there exists a Service and an Ingress definition.

Defining Services in HULL

The Service template contents of /templates/service.yaml:

cat ../kubernetes-dashboard/templates/service.yaml

do look like this:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: v1
kind: Service
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  labels:
    {{ include "kubernetes-dashboard.labels" . | nindent 4 }}
    app.kubernetes.io/component: kubernetes-dashboard
    {{ .Values.service.clusterServiceLabel.key | nindent 4}}: {{ .Values.service.clusterServiceLabel.enabled | quote }}
    {{- if .Values.service.labels }}
    {{ toYaml .Values.service.labels | nindent 4 }}
    {{- end }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
    {{- if .Values.service.annotations }}
    {{ toYaml .Values.service.annotations | nindent 4 }}
    {{- end }}
spec:
  type: {{ .Values.service.type }}
  ports:
  - port: {{ .Values.service.externalPort }}
{{- if .Values.protocolHttp }}
    targetPort: http
    name: http
{{- else }}
    targetPort: https
    name: https
{{- end }}
{{- if hasKey .Values.service "nodePort" }}
    nodePort: {{ .Values.service.nodePort }}
{{- end }}
{{- if .Values.service.loadBalancerSourceRanges }}
  loadBalancerSourceRanges:
{{ toYaml .Values.service.loadBalancerSourceRanges | nindent 4 }}
{{- end }}
  selector:
{{ include "kubernetes-dashboard.matchLabels" . | nindent 4 }}
    app.kubernetes.io/component: kubernetes-dashboard
{{- if .Values.service.loadBalancerIP }}
  loadBalancerIP: {{ .Values.service.loadBalancerIP }}
{{- end }}

Again there is a reference to the .Values.protocolHttp property which now exists in the hull.config.specific section. The ports' name and targetPort are set dependent on protocolHttp while the externalPort is centrally defined. Therefore it makes sense to centralize access to externalPort under hull.config.specific, even more so because the externalPort is also accessed when defining the Ingress (more on that later). To do so execute:

sed '/^\s\s\s\sspecific/r'<(
      echo "      externalPort: 443"
    ) -i -- values.yaml

Apart from the ports there is only the selector worth discussing, the rest of the Service template is straightforward 1:1 mappings. But also check on the service block defaults in the kubernetes-dashboard's values.yaml with:

cat ../kubernetes-dashboard/values.yaml | grep "^service:" -B 1 -A 23

which prints:


service:
  type: ClusterIP
  # Dashboard service port
  externalPort: 443

  ## LoadBalancerSourcesRange is a list of allowed CIDR values, which are combined with ServicePort to
  ## set allowed inbound rules on the security group assigned to the master load balancer
  # loadBalancerSourceRanges: []

  ## A user-specified IP address for load balancer to use as External IP (if supported)
  # loadBalancerIP:

  ## Additional Kubernetes Dashboard Service annotations
  annotations: {}

  ## Here labels can be added to the Kubernetes Dashboard service
  labels: {}

  ## Enable or disable the kubernetes.io/cluster-service label. Should be disabled for GKE clusters >=1.15.
  ## Otherwise, the addon manager will presume ownership of the service and try to delete it.
  clusterServiceLabel:
    enabled: true
    key: "kubernetes.io/cluster-service"

The label kubernetes.io/cluster-service is added to the Service object and the enabled value serves as the value, this is represented in this part of the Service template:

    {{ .Values.service.clusterServiceLabel.key | nindent 4}}: {{ .Values.service.clusterServiceLabel.enabled | quote }}

While you could mimic the logic and move the clusterServiceLabel to the hull.config.specific section it does not offer any advantage over adding the label to the new service instance with the default value of true. A comment may be added of course to explain the deeper meaning of this label.

A closer look at `selector`s of Services

As previously highlighted, the selector matchLabels for workloads are automatically constructed from the following labels:

app.kubernetes.io/component: default
app.kubernetes.io/instance: release-name
app.kubernetes.io/name: kubernetes-dashboard

The Service object's selector's in HULL follow the same construction principle, so this means that any Service whose key is identical to a workload object instance the selector will match and the Service will front the pods of the workload. For our example, if you define either a Deployment, DaemonSet or StatefulSet with key dashboard, any Service object with the same key dashboard will match and pose as the Service object to the pods on the network level. This is what you want to achieve here, a Service for the dashboard Deployment. On a side note, for Jobs the selector property is omitted automatically by HULL because in this case the selector handling of Jobs is internally managed by Kubernetes.

So if you leave out the selector specification you will automatically have the default selector created but if you want to model the selector property yourself you can overwrite it explicitly. A use case for this is e.g. the creation of an additional headless Service for StatefulSets or any other more finegrained controlling of Service to Pod matching. For this there also exists a HULL transformation, the hull.util.transformation.selector or short _HT&, which will be put to use later on.

But for now here is the converted Service object for the dashboard employing the techniques that you already have learned:

echo '  objects:
    service:
      dashboard:
        labels:
          ## Enable or disable the kubernetes.io/cluster-service label. Should be disabled for GKE clusters >=1.15.
          ## Otherwise, the addon manager will presume ownership of the service and try to delete it.
          "kubernetes.io/cluster-service": "true"
        type: ClusterIP
        ports:
          http:
            enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
            port: _HT*hull.config.specific.externalPort
            targetPort: http
          https:
            enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
            port: _HT*hull.config.specific.externalPort
            targetPort: https' >> values.yaml

Defining Ingresses for inbound traffic

Next take a look at the original ingress definition with:

cat ../kubernetes-dashboard/templates/ingress.yaml

returning:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.ingress.enabled -}}
{{- $serviceName := include "kubernetes-dashboard.fullname" . -}}
{{- $servicePort := .Values.service.externalPort -}}
{{- $paths := .Values.ingress.paths -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- range $key, $value := .Values.ingress.labels }}
    {{ $key }}: {{ $value | quote }}
    {{- end }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
    {{- if not .Values.protocolHttp }}
    # Add https backend protocol support for ingress-nginx
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    # Add https backend protocol support for GKE
    service.alpha.kubernetes.io/app-protocols: '{"https":"HTTPS"}'
    {{- end }}
    {{- with .Values.ingress.annotations }}
    {{ toYaml . | nindent 4 }}
    {{- end }}
spec:
  {{- with .Values.ingress.className }}
  ingressClassName: {{ . | quote }}
  {{- end }}
  rules:
  {{- if .Values.ingress.hosts }}
  {{- range $host := .Values.ingress.hosts }}
    - host: {{ $host }}
      http:
        paths:
  {{- if len ($.Values.ingress.customPaths) }}
  {{- "\n" }}{{ tpl (toYaml $.Values.ingress.customPaths | nindent 10) $ }}
  {{- else }}
  {{- range $p := $paths }}
          - path: {{ $p }}
            pathType: ImplementationSpecific
            backend:
              service:
                name: {{ $serviceName }}
                port:
                  number: {{ $servicePort }}
  {{- end -}}
  {{- end -}}
  {{- end -}}
  {{- else }}
    - http:
        paths:
  {{- if len ($.Values.ingress.customPaths) }}
  {{- "\n" }}{{ tpl (toYaml $.Values.ingress.customPaths | nindent 10) $ }}
  {{- else }}
  {{- range $p := $paths }}
          - path: {{ $p }}
            pathType: ImplementationSpecific
            backend:
              service:
                name: {{ $serviceName }}
                port:
                  number: {{ $servicePort }}
  {{- end -}}
  {{- end -}}
  {{- end -}}
  {{- if .Values.ingress.tls }}
  tls:
{{ toYaml .Values.ingress.tls | nindent 4 }}
  {{- end -}}
{{- end -}}

This is what the values.yaml has to say about the ingress definition:

cat ../kubernetes-dashboard/values.yaml | grep "^ingress:" -B 1 -A 59

which is:


ingress:
  ## If true, Kubernetes Dashboard Ingress will be created.
  ##
  enabled: false

  ## Kubernetes Dashboard Ingress labels
  # labels:
  #   key: value

  ## Kubernetes Dashboard Ingress annotations
  # annotations:
  #   kubernetes.io/ingress.class: nginx
  #   kubernetes.io/tls-acme: 'true'

  ## If you plan to use TLS backend with enableInsecureLogin set to false
  ## (default), you need to uncomment the below.
  ## If you use ingress-nginx < 0.21.0
  #   nginx.ingress.kubernetes.io/secure-backends: "true"
  ## if you use ingress-nginx >= 0.21.0
  #   nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

  ## Kubernetes Dashboard Ingress Class
  # className: "example-lb"

  ## Kubernetes Dashboard Ingress paths
  ## Both `/` and `/*` are required to work on gce ingress.
  paths:
    - /
  #  - /*

  ## Custom Kubernetes Dashboard Ingress paths. Will override default paths.
  ##
  customPaths: []
  #  - pathType: ImplementationSpecific
  #    backend:
  #      service:
  #        name: ssl-redirect
  #        port:
  #          name: use-annotation
  #  - pathType: ImplementationSpecific
  #    backend:
  #      service:
  #        name: >-
  #          {{ include "kubernetes-dashboard.fullname" . }}
  #        port:
  #          # Don't use string here, use only integer value!
  #          number: 443
  ## Kubernetes Dashboard Ingress hostnames
  ## Must be provided if Ingress is enabled
  ##
  # hosts:
  #   - kubernetes-dashboard.domain.com
  ## Kubernetes Dashboard Ingress TLS configuration
  ## Secrets must be manually created in the namespace
  ##
  # tls:
  #   - secretName: kubernetes-dashboard-tls
  #     hosts:
  #       - kubernetes-dashboard.domain.com

The values.yaml documentation is a little confusing and the template quite difficult to decipher at once so break it apart to see what is happening here:

annotations are to be added to the ingress on the condition that protocolHttp is not true. Excerpt from ingress template:

  {{- if not .Values.protocolHttp }}
    # Add https backend protocol support for ingress-nginx
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    # Add https backend protocol support for GKE
    service.alpha.kubernetes.io/app-protocols: '{"https":"HTTPS"}'
    {{- end }}

the rules entries section is basically repeated in the template, one time for all the hosts if any are given or once without host property if no hosts are given. Regarding the paths to process in both blocks the template will write out all fully specified customPaths if any are provided or will iterate over the predefined paths if no customPaths are given where the paths all point to the dashboard Service:

  rules:
  {{- if .Values.ingress.hosts }}
  {{- range $host := .Values.ingress.hosts }}
    - host: {{ $host }}
      http:
        paths:
  {{- if len ($.Values.ingress.customPaths) }}
  {{- "\n" }}{{ tpl (toYaml $.Values.ingress.customPaths | nindent 10) $ }}
  {{- else }}
  {{- range $p := $paths }}
          - path: {{ $p }}
            pathType: ImplementationSpecific
            backend:
              service:
                name: {{ $serviceName }}
                port:
                  number: {{ $servicePort }}
  {{- end -}}
  {{- end -}}
  {{- end -}}
  {{- else }}
    - http:
        paths:
  {{- if len ($.Values.ingress.customPaths) }}
  {{- "\n" }}{{ tpl (toYaml $.Values.ingress.customPaths | nindent 10) $ }}
  {{- else }}
  {{- range $p := $paths }}
          - path: {{ $p }}
            pathType: ImplementationSpecific
            backend:
              service:
                name: {{ $serviceName }}
                port:
                  number: {{ $servicePort }}
  {{- end -}}
  {{- end -}}
  {{- end -}}

Here is a simple approach to model this ingress where the default rule is being added as would be the case in the original values.yaml configuration:

echo '    ingress:
      dashboard:
        enabled: false
        annotations: |- 
          _HT!{
            {{ if not (index . "$").Values.hull.config.specific.protocolHttp }}
            "nginx.ingress.kubernetes.io/backend-protocol": "HTTPS",
            "service.alpha.kubernetes.io/app-protocols": "{\"https\":\"HTTPS\"}"
            {{ end }}
          }
        rules:
          default:
            http:
              paths:
                root:
                  path: /
                  pathType: ImplementationSpecific
                  backend:
                    service:
                      name: dashboard
                      port:
                        number: _HT*hull.config.specific.externalPort' >> values.yaml

If you need to change it at deploy time you could:

add a host to the default path
alter the path for the default rule for example to match your wanted route
set the rule for default: null in which it will not be rendered anymore and create your own rule

As a sanity check you should enable the ingress to see it prints out as expected:

echo 'hull:
  objects:
    ingress:
      dashboard:
        enabled: true' > ../configs/enable-ingress.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/enable-ingress.yaml .

and there it is:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Service
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    kubernetes.io/cluster-service: "true"
  name: release-name-kubernetes-dashboard-dashboard
spec:
  ports:
  - name: https
    port: 443
    targetPort: https
  selector:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/name: kubernetes-dashboard
  type: ClusterIP
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
    service.alpha.kubernetes.io/app-protocols: '{"https":"HTTPS"}'
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  rules:
  - host:
    http:
      paths:
      - backend:
          service:
            name: release-name-kubernetes-dashboard-dashboard
            port:
              number: 443
        path: /
        pathType: ImplementationSpecific
  tls: []

Since the protocolHttp option has a significant effect on the rendered output also do a quick test if everything is in order:

echo 'hull:
  config:
    specific:
      protocolHttp: true
  objects:
    ingress:
      dashboard:
        enabled: true' > ../configs/enable-ingress-http.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/enable-ingress-http.yaml .

and there it is:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Service
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    kubernetes.io/cluster-service: "true"
  name: release-name-kubernetes-dashboard-dashboard
spec:
  ports:
  - name: http
    port: 443
    targetPort: http
  selector:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/name: kubernetes-dashboard
  type: ClusterIP
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  rules:
  - host:
    http:
      paths:
      - backend:
          service:
            name: release-name-kubernetes-dashboard-dashboard
            port:
              number: 443
        path: /
        pathType: ImplementationSpecific
  tls: []

Another Wrap Up

So to finish this quickly:

That is how your values.yamlshould look right now:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      externalPort: 443
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}
  objects:
    service:
      dashboard:
        labels:
          ## Enable or disable the kubernetes.io/cluster-service label. Should be disabled for GKE clusters >=1.15.
          ## Otherwise, the addon manager will presume ownership of the service and try to delete it.
          "kubernetes.io/cluster-service": "true"
        type: ClusterIP
        ports:
          http:
            enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
            port: _HT*hull.config.specific.externalPort
            targetPort: http
          https:
            enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
            port: _HT*hull.config.specific.externalPort
            targetPort: https
    ingress:
      dashboard:
        enabled: false
        annotations: |-
          _HT!{
            {{ if not (index . "$").Values.hull.config.specific.protocolHttp }}
            "nginx.ingress.kubernetes.io/backend-protocol": "HTTPS",
            "service.alpha.kubernetes.io/app-protocols": "{\"https\":\"HTTPS\"}"
            {{ end }}
          }
        rules:
          default:
            http:
              paths:
                root:
                  path: /
                  pathType: ImplementationSpecific
                  backend:
                    service:
                      name: dashboard
                      port:
                        number: _HT*hull.config.specific.externalPort

Run the values.yaml backup:

cp values.yaml values.tutorial-part.yaml

Add in the already created objects:

sed '1,/objects:/d' values.full.yaml > _tmp && cp values.yaml values.full.yaml && cat _tmp >> values.full.yaml && rm _tmp

Thanks for taking part and hope to see you in the next tutorial part on advanced object configuration as well!

HULL Tutorial 05: Defining Workload objects

gre9ory — Tue, 31 May 2022 11:25:10 +0000

Preparation

In this Part of the tutorial workload objects are created. A workload object has a pod at its core in which containers run code. Most important workload types are Deployments, DaemonSets, StatefulSets, Jobs and CronJobs.

First off we again copy over our working chart from the last tutorial part to a new folder in the same manner as we did before. Go to your working directory and execute:

cd ~/kubernetes-dashboard-hull && cp -R 04_rbac/ 05_workloads && cd 05_workloads/kubernetes-dashboard-hull

As before, to delete the HULL hull.objects from values.full.yaml and copy the current hull.config to the values.yaml type the following:

sed '/  objects:/Q' values.full.yaml > values.yaml

and verify the result:

cat values.yaml

looks like:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}

If yes, then you are good to start the next tutorial part.

Examining existing workloads

Now having the preparation out of the way first find out which of those mentioned workload objects are present in the original chart:

find ../kubernetes-dashboard/templates -type f -iregex '.*\(deployment\|daemonset\|statefulset\|job\).*' | sort

which returns:

../kubernetes-dashboard/templates/deployment.yaml

Only the dashboard deployment but it will suffice to explain the process.

Specifying workloads with HULL

Now check the templates/deployment.yaml Deployment:

cat ../kubernetes-dashboard/templates/deployment.yaml

which is defined as follows:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
    {{- with .Values.annotations }}
    {{ toYaml . | nindent 4 }}
    {{- end }}
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    app.kubernetes.io/component: kubernetes-dashboard
    {{- with .Values.labels }}
    {{ toYaml . | nindent 4 }}
    {{- end }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
spec:
  replicas: {{ .Values.replicaCount }}
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  selector:
    matchLabels:
{{ include "kubernetes-dashboard.matchLabels" . | nindent 6 }}
      app.kubernetes.io/component: kubernetes-dashboard
  template:
    metadata:
      annotations:
        {{- if .Values.podAnnotations }}
        {{- include "common.tplvalues.render" (dict "value" .Values.podAnnotations "context" $) | nindent 8 }}
        {{- end }}
      labels:
        {{- include "kubernetes-dashboard.labels" . | nindent 8 }}
        app.kubernetes.io/component: kubernetes-dashboard
        {{- if .Values.podLabels }}
        {{- include "common.tplvalues.render" (dict "value" .Values.podLabels "context" $) | nindent 8 }}
        {{- end }}
    spec:
{{- with .Values.securityContext }}
      securityContext:
{{ toYaml . | nindent 8 }}
{{- end }}
      serviceAccountName: {{ template "kubernetes-dashboard.serviceAccountName" . }}
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        args:
          - --namespace={{ .Release.Namespace }}
{{- if not .Values.protocolHttp }}
          - --auto-generate-certificates
{{- end }}
{{- if .Values.metricsScraper.enabled }}
          - --sidecar-host=http://127.0.0.1:8000
{{- else }}
          - --metrics-provider=none
{{- end }}
{{- with .Values.extraArgs }}
{{ toYaml . | nindent 10 }}
{{- end }}
{{- with .Values.extraEnv }}
        env:
{{ toYaml . | nindent 10 }}
{{- end }}
        ports:
{{- if .Values.protocolHttp }}
        - name: http
          containerPort: 9090
          protocol: TCP
{{- else }}
        - name: https
          containerPort: 8443
          protocol: TCP
{{- end }}
        volumeMounts:
        - name: kubernetes-dashboard-certs
          mountPath: /certs
          # Create on-disk volume to store exec logs
        - mountPath: /tmp
          name: tmp-volume
{{- with .Values.extraVolumeMounts }}
{{ toYaml . | nindent 8 }}
{{- end }}
        livenessProbe:
          httpGet:
{{- if .Values.protocolHttp }}
            scheme: HTTP
            path: /
            port: 9090
{{- else }}
            scheme: HTTPS
            path: /
            port: 8443
{{- end }}
          initialDelaySeconds: {{ .Values.livenessProbe.initialDelaySeconds }}
          timeoutSeconds: {{ .Values.livenessProbe.timeoutSeconds }}
{{- with .Values.resources }}
        resources:
{{ toYaml . | nindent 10 }}
{{- end }}
{{- with .Values.containerSecurityContext }}
        securityContext:
{{ toYaml . | nindent 10 }}
{{- end }}
{{- if .Values.metricsScraper.enabled }}
      - name: dashboard-metrics-scraper
        image: "{{ .Values.metricsScraper.image.repository }}:{{ .Values.metricsScraper.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
{{- with .Values.metricsScraper.args }}
        args:
{{ toYaml . | nindent 10 }}
{{- end }}
        ports:
          - containerPort: 8000
            protocol: TCP
        livenessProbe:
          httpGet:
            scheme: HTTP
            path: /
            port: 8000
          initialDelaySeconds: {{ .Values.livenessProbe.initialDelaySeconds }}
          timeoutSeconds: {{ .Values.livenessProbe.timeoutSeconds }}
        volumeMounts:
        - mountPath: /tmp
          name: tmp-volume

{{- if .Values.metricsScraper.containerSecurityContext }}
        securityContext:
{{ toYaml .Values.metricsScraper.containerSecurityContext | nindent 10 }}
{{- else if .Values.containerSecurityContext}}
        securityContext:
{{ toYaml .Values.containerSecurityContext | nindent 10 }}
{{- end }}
{{- with .Values.metricsScraper.resources }}
        resources:
{{ toYaml . | nindent 10 }}
{{- end }}
{{- end }}
{{- with .Values.image.pullSecrets }}
      imagePullSecrets:
{{- range . }}
        - name: {{ . }}
{{- end }}
{{- end }}
{{- with .Values.nodeSelector }}
      nodeSelector:
{{ toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.priorityClassName }}
      priorityClassName: "{{ . }}"
{{- end }}
      volumes:
      - name: kubernetes-dashboard-certs
        secret:
          secretName: {{ template "kubernetes-dashboard.fullname" . }}-certs
      - name: tmp-volume
        emptyDir: {}
{{- with .Values.extraVolumes }}
{{ toYaml . | nindent 6 }}
{{- end }}
{{- with .Values.tolerations }}
      tolerations:
{{ toYaml . | nindent 8 }}
{{- end }}
{{- with .Values.affinity }}
      affinity:
{{ toYaml . | nindent 8 }}
{{- end }}

Many Helm charts are full of 1:1 mappings between values.yaml properties and the target object's properties of the same type in the /templates files. Cases in point for the above Deployment are:

{{- with .Values.securityContext }}
      securityContext:
{{ toYaml . | nindent 8 }}

{{- with .Values.containerSecurityContext }}
        securityContext:
{{ toYaml . | nindent 10 }}
{{- end }}

{{- with .Values.metricsScraper.resources }}
        resources:
{{ toYaml . | nindent 10 }}
{{- end }}

{{- with .Values.image.pullSecrets }}
      imagePullSecrets:
{{- range . }}
        - name: {{ . }}
{{- end }}
{{- end }}

{{- with .Values.nodeSelector }}
      nodeSelector:
{{ toYaml . | nindent 8 }}
{{- end }}

There are a couple of more but the point of 1:1 mappings should be clear.
Now here one of or maybe the major strength of HULL comes into play: setting any object property can be done directly without the need to write any repetitive boilerplate code in the sense of:

if this value is provided in values.yaml do insert it here 'as is' in the template

Using HULL all of the shown code blocks can be ignored for our conversion because we can configure the properties without any additional required action at configuration/deployment time if needed. No additional pull request needed to make them configurable, they are always accessible if changing them is required.

Automated `selector` population

Selectors for pods are automatically created by HULL and take the unique metadata combination of the labels:

app.kubernetes.io/component: default
app.kubernetes.io/instance: release-name
app.kubernetes.io/name: kubernetes-dashboard

into account. With these fields being autopopulated at the workload and pod label level nothing further needs to be specified.

Specifying the Pod `template`

These are the new and interesting aspects when investigating the Deployments pod specification we need to deal with:

The main container `name`

A quick note on the actual main container name which depends on the chart name in the original kubernetes-dashboard chart:

- name: {{ .Chart.Name }}

Here the container name will always resort to kubernetes-dashboard but it may also be bound to some other value in the values.yaml. Since with HULL the name is derived by the container's key, changing the key in a system specific configuration would require to redefine all the containers content which is not desired. Hence you have to stick with the static defined container name kubernetes-dashboard in the HULL version of the chart but normally container names are of minimal importance to the Deployment.

The `imagePullSecrets` and `image.registry` feature

A word on imagePullSecrets though: it is very easy to configure and use them with HULL throughout all workloads which should be briefly highlighted.

Firstly, HULL splits the image definition of containers into three parts which are concatenated to form the image value in the Pod spec:

registry
repository
tag

where the leading registry part is optional.

Secondly there is a dedicated object type named registry where you can specify Docker Registry secrets. With dedicated registry fields in the image definition and the dedicated registry objects, HULL by default adds all registry objects that are created in HULL as imagePullSecrets to the pod specs so images are always pullable even if they are stored on a configured secured registry. If this behavior is undesired, you can disable this feature simply by setting createImagePullSecretsFromRegistries to false in the HULL configuration like this:

hull:
  config:
    general:
      createImagePullSecretsFromRegistries: false

You can however combine this feature with the possibility to set all pods registry fields to a common value. This is allowed for either using a fixed registry server name (for which the Docker registry secret is deployed outside of the Helm chart) or for using the server defined in the first found registry secret that is configured in the same chart.

To provide an example of a real life use case imagine you host all Docker images referenced in your Helm chart in one place - meaning in one Docker registry. Now you may want to switch Docker registry providers - and hence the endpoint - or you need to copy over all Docker images to an airgapped system and host them in a local secured registry such as Harbor. In both cases you may want to centrally change the registry servers address without having to configure each pod specs imagePullSecrets and each containers image individually.

To use a static server name you can populate the hull.config.general.defaultImageRegistryServer field, this requires you to add the imagePullSecrets yourself to the pod specs. If you define the registry within the same chart you may just enable hull.config.general.defaultImageRegistryToFirstRegistrySecretServer and all is done automatically in terms of imagePullSecrets and registry population.

Refer to the documentation and the following config switches:

hull:
  config:
    general:
      defaultImageRegistryServer:
      defaultImageRegistryToFirstRegistrySecretServer:

for more details on how to work with this feature.

Dynamically creating `args`

The args section requires using a HULL transformation to create an array of arguments that match the dynamic nature of the argument construction.

Seperating out configuration to `hull.config.specific`

Multiple pod specific properties are referencing properties under the .Values.metricsScraper section in the original charts values.yaml:

{{- if .Values.metricsScraper.enabled }}
          - --sidecar-host=http://127.0.0.1:8000
{{- else }}
          - --metrics-provider=none
{{- end }}

and:

{{- if .Values.metricsScraper.enabled }}
      - name: dashboard-metrics-scraper
        image: "{{ .Values.metricsScraper.image.repository }}:{{ .Values.metricsScraper.image.tag }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
{{- with .Values.metricsScraper.args }}
        args:
{{ toYaml . | nindent 10 }}
{{- end }}
        ports:
          - containerPort: 8000
            protocol: TCP
        livenessProbe:
          httpGet:
            scheme: HTTP
            path: /
            port: 8000
          initialDelaySeconds: {{ .Values.livenessProbe.initialDelaySeconds }}
          timeoutSeconds: {{ .Values.livenessProbe.timeoutSeconds }}
        volumeMounts:
        - mountPath: /tmp
          name: tmp-volume

{{- if .Values.metricsScraper.containerSecurityContext }}
        securityContext:
{{ toYaml .Values.metricsScraper.containerSecurityContext | nindent 10 }}
{{- else if .Values.containerSecurityContext}}
        securityContext:
{{ toYaml .Values.containerSecurityContext | nindent 10 }}
{{- end }}
{{- with .Values.metricsScraper.resources }}
        resources:
{{ toYaml . | nindent 10 }}
{{- end }}
{{- end }}

Basically it boils down to an optional sidecar container dashboard-metrics-scraper which may be enabled at will. The relevant section in values.yaml:

cat ../kubernetes-dashboard/values.yaml | grep "metricsScraper" -B 4 -A 17

looks as follows:


## Metrics Scraper
## Container to scrape, store, and retrieve a window of time from the Metrics Server.
## refs: https://github.com/kubernetes-sigs/dashboard-metrics-scraper
metricsScraper:
  ## Wether to enable dashboard-metrics-scraper
  enabled: false
  image:
    repository: kubernetesui/metrics-scraper
    tag: v1.0.7
  resources: {}
  ## SecurityContext especially for the kubernetes dashboard metrics scraper container
  ## If not set, the global containterSecurityContext values will define these values
  # containerSecurityContext:
  #   allowPrivilegeEscalation: false
  #   readOnlyRootFilesystem: true
  #   runAsUser: 1001
  #   runAsGroup: 2001
#  args:
#    - --log-level=info
#    - --logtostderr=true

To model this in your HULL chart you can just predefine the side car container and set enabled: false on it so it will behave the same as in the original chart. Regarding the reference in the args it can be hooked up with the enabled property. You may of course reference and specify the metricsScraper.enabled property in the hull.config.specific section to highlight the feature itself but it's not done in this tutorial. Most important for a proper Helm chart is to document the values.yaml appropriately as to how the metricsScraper can be enabled, for the sake of brevity documentation and comments on the values.yaml are generally omitted.

Back to the pod specification, the .Values.protocolHttp property is also accessed multiple times too:

{{- if not .Values.protocolHttp }}
          - --auto-generate-certificates
{{- end }}

and:

{{- if .Values.protocolHttp }}
        - name: http
          containerPort: 9090
          protocol: TCP
{{- else }}
        - name: https
          containerPort: 8443
          protocol: TCP
{{- end }}

This property is suitable to be added in the hull.config.specific section to allow centrally switching to HTTP mode. Properties such as these can be considered custom more abstract properties that do not directly translate to one object property but control multiple aspects of maybe multiple objects even. Other properties are more concrete properties which are directly associated with an object property (e.g. imagePullPolicy, affinity, tolerations, ...)

The custom abstract properties are best modeled somewhere under hull.config.specific but for the concrete ones are best defined at deploy time by the configurator of the chart, adding redirection to hull.config.specific can clutter the configurational transparency.

But there are exceptions, e.g. consider a Helm chart allows to deploy it's application as either a Deployment or DaemonSet and shares a large amount of both objects configuration via a shared pod template definition:

if you aim for transparency it is best to define the properties directly on the DaemonSet and Deployment objects so the same property can have different values configured for both of them.

Advantage here is that it is more straightforward to understand where each object's property value is defined if at all and how it can be changed.

Disadvantage is that this weakens the likely intention to have the DaemonSet and Deployment as alike as possible since it allows to involuntarily have unwanted differences between them.
if you aim for abstraction you should define all the properties that are being referenced from both Deployment and DaemonSet under the hull.config.specific section and reference the central values.

Disadvantage is that it obfuscates where a properties value comes from more and requires much more effort to set up the chart.

Advantages are that the intent of having DaemonSet and Deployment as much alike as possible is better fulfillable and it would still be possible to overwrite any individual property on object level if wanted.

Putting it all together

Ok so first insert the new hull.config.specific property so it can be referenced to:

sed '/^\s\s\s\sspecific/r'<(
      echo "      protocolHttp: false"
    ) -i -- values.yaml

Good, now when writing the Deployment spec default property values can be taken from the relevant fields in the original values.yaml where they are provided. For example, the values.yaml holds defaults for securityContext's:

cat ../kubernetes-dashboard/values.yaml | grep "securityContext" -B 3 -A 12

of the pod and the main container and a commented out suggestion for the metricsScraper container:


## SecurityContext to be added to kubernetes dashboard pods
## To disable set the following configuration to null:
# securityContext: null
securityContext:
  seccompProfile:
    type: RuntimeDefault

## SecurityContext defaults for the kubernetes dashboard container and metrics scraper container
## To disable set the following configuration to null:
# containerSecurityContext: null
containerSecurityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  runAsUser: 1001
  runAsGroup: 2001

--
  ## Maximum unavailable instances; ignored if there is no PodDisruptionBudget
  maxUnavailable:

## PodSecurityContext for pod level securityContext
# securityContext:
#   runAsUser: 1001
#   runAsGroup: 2001

networkPolicy:
  # Whether to create a network policy that allows/restricts access to the service
  enabled: false

## podSecurityPolicy for fine-grained authorization of pod creation and updates
podSecurityPolicy:
  # Specifies whether a pod security policy should be created
  enabled: false

Many more fields that have simple defaults in the kubernetes-dashboard's values.yaml can be copied over to our new HULL based Deployment specification, amongst them image, resources and imagePullSecrets.

Other YAML structures in the Deployment are mixtures of static content and templated parts, take a look at the original args:

        args:
          - --namespace={{ .Release.Namespace }}
{{- if not .Values.protocolHttp }}
          - --auto-generate-certificates
{{- end }}
{{- if .Values.metricsScraper.enabled }}
          - --sidecar-host=http://127.0.0.1:8000
{{- else }}
          - --metrics-provider=none
{{- end }}
{{- with .Values.extraArgs }}
{{ toYaml . | nindent 10 }}
{{- end }}

or are build up completely based on templating decisions like the ports:

        ports:
{{- if .Values.protocolHttp }}
        - name: http
          containerPort: 9090
          protocol: TCP
{{- else }}
        - name: https
          containerPort: 8443
          protocol: TCP
{{- end }}

To replicate this behavior you can use the _HT! HULL transformation to completely model the arrays or dictionaries as desired or - in case of the simpler either/or decision for the ports - you can utilize hooking up the individual port definitions enabled property to a condition as shown next. HULL offers flexibility to model the configuration as you think it fits best.

So this is a proposition for modeling the suggested Deployment spec for the kubernetes-dashboard-hull chart:

echo '  objects:
    deployment:
      dashboard:
        enabled: true
        replicas: 1
        strategy:
          rollingUpdate:
            maxSurge: 0
            maxUnavailable: 1
          type: RollingUpdate
        pod:
          securityContext:
            seccompProfile:
              type: RuntimeDefault
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: v2.5.0
              imagePullPolicy: IfNotPresent
              args: _HT![
                  {{- $p := (index . "$") }}
                  "--namespace={{ $p.Release.Namespace }}",
                  {{- if not $p.Values.hull.config.specific.protocolHttp }}
                  "--auto-generate-certificates",
                  {{- end }}
                  {{- if $p.Values.hull.objects.deployment.dashboard.pod.containers.metricsscraper.enabled }}
                  "--sidecar-host=http://127.0.0.1:8000",
                  {{- else }}
                  "--metrics-provider=none",
                  {{- end }}
                  ]
              ports:
                http:
                  enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
                  containerPort: 9090
                  protocol: TCP
                https:
                  enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
                  containerPort: 8443
                  protocol: TCP
              volumeMounts:
                dashboard:
                  name: kubernetes-dashboard-certs
                  mountPath: /certs
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              livenessProbe: |-
                _HT!{
                  httpGet: {
                    path: /,
                    scheme: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary "HTTP" "HTTPS" }},
                    port: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary 9090 8443 }}
                    }
                  }
                initialDelaySeconds: 30
                timeoutSeconds: 30
              resources:
                requests:
                  cpu: 100m
                  memory: 200Mi
                limits:
                  cpu: 2
                  memory: 200Mi
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
            metricsscraper:
              enabled: false
              image:
                repository: kubernetesui/metrics-scraper
                tag: v1.0.7
              imagePullPolicy: IfNotPresent
              ports:
                tcp:
                  containerPort: 8000
                  protocol: TCP
              livenessProbe:
                httpGet:
                  scheme: HTTP
                  path: /
                  port: 8000
                initialDelaySeconds: 30
                timeoutSeconds: 30
              volumeMounts:
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
          volumes:
            kubernetes-dashboard-certs:
              secret:
                secretName: certs
            tmp-volume:
              emptyDir: {}' >> values.yaml

Does it render as expected?

helm template -f ../configs/disable-default-rbac.yaml .

yields:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - args:
        - --namespace=default
        - --auto-generate-certificates
        - --metrics-provider=none
        env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        imagePullPolicy: IfNotPresent
        livenessProbe:
          httpGet:
            path: /
            port: 8443
            scheme: HTTPS
        name: dashboard
        ports:
        - containerPort: 8443
          name: https
          protocol: TCP
        resources:
          limits:
            cpu: 2
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsGroup: 2001
          runAsUser: 1001
        volumeMounts:
        - mountPath: /certs
          name: kubernetes-dashboard-certs
        - mountPath: /tmp
          name: tmp-volume
      imagePullSecrets: []
      initContainers: []
      securityContext:
        seccompProfile:
          type: RuntimeDefault
      volumes:
      - name: kubernetes-dashboard-certs
        secret:
          secretName: release-name-kubernetes-dashboard-certs
      - emptyDir: {}
        name: tmp-volume

Everything should be as expected. How about switching to HTTP and enabling the metricsscraper for a test?

echo 'hull:
  config:
    specific:
      protocolHttp: true
  objects:
    deployment:
      dashboard:
        pod:
          containers:
            metricsscraper:
              enabled: true' > ../configs/enable-http-scraper.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/enable-http-scraper.yaml .

and you'll see that the args, ports and livenessProbe output has changed to reflect the change to the protocolHttp property and the metricsscraper container is activated:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - args:
        - --namespace=default
        - --sidecar-host=http://127.0.0.1:8000
        env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        imagePullPolicy: IfNotPresent
        livenessProbe:
          httpGet:
            path: /
            port: 9090
            scheme: HTTP
        name: dashboard
        ports:
        - containerPort: 9090
          name: http
          protocol: TCP
        resources:
          limits:
            cpu: 2
            memory: 200Mi
          requests:
            cpu: 100m
            memory: 200Mi
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsGroup: 2001
          runAsUser: 1001
        volumeMounts:
        - mountPath: /certs
          name: kubernetes-dashboard-certs
        - mountPath: /tmp
          name: tmp-volume
      - env: []
        envFrom: []
        image: kubernetesui/metrics-scraper:v1.0.7
        imagePullPolicy: IfNotPresent
        livenessProbe:
          httpGet:
            path: /
            port: 8000
            scheme: HTTP
          initialDelaySeconds: 30
          timeoutSeconds: 30
        name: metricsscraper
        ports:
        - containerPort: 8000
          name: tcp
          protocol: TCP
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsGroup: 2001
          runAsUser: 1001
        volumeMounts:
        - mountPath: /tmp
          name: tmp-volume
      imagePullSecrets: []
      initContainers: []
      securityContext:
        seccompProfile:
          type: RuntimeDefault
      volumes:
      - name: kubernetes-dashboard-certs
        secret:
          secretName: release-name-kubernetes-dashboard-certs
      - emptyDir: {}
        name: tmp-volume

Wrap Up

Thanks for your interest, your values.yaml is supposed to look like this at this point:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      protocolHttp: false
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}
  objects:
    deployment:
      dashboard:
        enabled: true
        replicas: 1
        strategy:
          rollingUpdate:
            maxSurge: 0
            maxUnavailable: 1
          type: RollingUpdate
        pod:
          securityContext:
            seccompProfile:
              type: RuntimeDefault
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: v2.5.0
              imagePullPolicy: IfNotPresent
              args: _HT![
                  {{- $p := (index . "$") }}
                  "--namespace={{ $p.Release.Namespace }}",
                  {{- if not $p.Values.hull.config.specific.protocolHttp }}
                  "--auto-generate-certificates",
                  {{- end }}
                  {{- if $p.Values.hull.objects.deployment.dashboard.pod.containers.metricsscraper.enabled }}
                  "--sidecar-host=http://127.0.0.1:8000",
                  {{- else }}
                  "--metrics-provider=none",
                  {{- end }}
                  ]
              ports:
                http:
                  enabled: _HT?(index . "$").Values.hull.config.specific.protocolHttp
                  containerPort: 9090
                  protocol: TCP
                https:
                  enabled: _HT?(not (index . "$").Values.hull.config.specific.protocolHttp)
                  containerPort: 8443
                  protocol: TCP
              volumeMounts:
                dashboard:
                  name: kubernetes-dashboard-certs
                  mountPath: /certs
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              livenessProbe: |-
                _HT!{
                  httpGet: {
                    path: /,
                    scheme: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary "HTTP" "HTTPS" }},
                    port: {{ (index . "$").Values.hull.config.specific.protocolHttp | ternary 9090 8443 }}
                    }
                  }
                initialDelaySeconds: 30
                timeoutSeconds: 30
              resources:
                requests:
                  cpu: 100m
                  memory: 200Mi
                limits:
                  cpu: 2
                  memory: 200Mi
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
            metricsscraper:
              enabled: false
              image:
                repository: kubernetesui/metrics-scraper
                tag: v1.0.7
              imagePullPolicy: IfNotPresent
              ports:
                tcp:
                  containerPort: 8000
                  protocol: TCP
              livenessProbe:
                httpGet:
                  scheme: HTTP
                  path: /
                  port: 8000
                initialDelaySeconds: 30
                timeoutSeconds: 30
              volumeMounts:
                tmp:
                  name: tmp-volume
                  mountPath: /tmp
              securityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsUser: 1001
                runAsGroup: 2001
          volumes:
            kubernetes-dashboard-certs:
              secret:
                secretName: certs
            tmp-volume:
              emptyDir: {}

Again backup your finished values.yaml to the values.tutorial-part.yaml in case you want to modify, play around or start from scratch again with the values.yaml:

cp values.yaml values.tutorial-part.yaml

and add in the objects things created in the previous tutorial:

sed '1,/objects:/d' values.full.yaml > _tmp && cp values.yaml values.full.yaml && cat _tmp >> values.full.yaml && rm _tmp

Hope to see you in the next tutorial on Services and Ingresses!

HULL Tutorial 04: Configuring ServiceAccounts and RBAC

gre9ory — Tue, 31 May 2022 11:24:56 +0000

Preparation

After the ConfigMaps and Secrets tutorial part this part will look at the RBAC configuration side of kubernetes-dashboard's Helm chart and check how it is transportable to the new HULL based kubernetes-dashboard-hull chart.

Initially you should copy over our working chart from the last tutorial part to a new folder in the same manner as we did before. Go to your working directory and execute:

cd ~/kubernetes-dashboard-hull && cp -R 03_configmaps_and_secrets/ 04_rbac && cd 04_rbac/kubernetes-dashboard-hull

From the values.full.yaml, the starting point for this tutorial part, only keep the hull.config.specific section for building upon in this chapter, the hull.objects section should be cleared for now since you will only add objects relevant to this tutorial section to it. At the end of this tutorial part the newly created objects and newly added hull.config.specific properties are added to the values.full.yaml with what was already created. This in turn will then serve as the next tutorial parts starting point.

To delete the HULL objects from values.full.yaml and copy the rest of our values.yaml to the values.yaml type the following:

sed '/  objects:/Q' values.full.yaml > values.yaml

and verify the result in the new values.yaml:

cat values.yaml

to show only the hull.config.specific section:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      settings: {}
      pinnedCRDs: {}

Let's get started on ServiceAccount configuration and role based access control!

Examining the existing RBAC objects

Execute the following command to first get an idea which RBAC objects are defined:

find ../kubernetes-dashboard/templates -type f -iregex '.*\(Role\|\role|\Account\|account\|rbac\|RBAC\).*' | sort

which reveals them all:

../kubernetes-dashboard/templates/clusterrole-metrics.yaml
../kubernetes-dashboard/templates/clusterrole-readonly.yaml
../kubernetes-dashboard/templates/clusterrolebinding-metrics.yaml
../kubernetes-dashboard/templates/clusterrolebinding-readonly.yaml
../kubernetes-dashboard/templates/role.yaml
../kubernetes-dashboard/templates/rolebinding.yaml
../kubernetes-dashboard/templates/serviceaccount.yaml

In the previous tutorial part when you created the kubernetes-dashboard-hull chart you already had a glance at the default RBAC configuration that comes with HULL. So now is the time to adapt and tweak it so it matches the original Helm charts RBAC functionally as closely as possible.

First check the ServiceAccount:

cat ../kubernetes-dashboard/templates/serviceaccount.yaml

which is this:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.serviceAccount.create -}}
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
  name: {{ template "kubernetes-dashboard.serviceAccountName" . }}
{{- end -}}

The actual creation of the ServiceAccount name is deferred to a helper function in _helpers.tpl which we look at in more detail:

cat ../kubernetes-dashboard/templates/_helpers.tpl | grep 'kubernetes-dashboard\.serviceAccountName' -B 4 -A 10

where the inherent logic becomes more apparent:


{{/*
Name of the service account to use
*/}}
{{- define "kubernetes-dashboard.serviceAccountName" -}}
{{- if .Values.serviceAccount.create -}}
    {{ default (include "kubernetes-dashboard.fullname" .) .Values.serviceAccount.name }}
{{- else -}}
    {{ default "default" .Values.serviceAccount.name }}
{{- end -}}
{{- end -}}

Now check the values.yaml section dealing with the serviceAccount configuration:

cat ../kubernetes-dashboard/values.yaml | grep '^serviceAccount' -B 1 -A 6

for completing our examination of the controllers ServiceAccount configuration:


serviceAccount:
  # Specifies whether a service account should be created
  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:

Now you should have garnered an impression of the ServiceAccount configuration options and relations which is actually a typical way to model this aspect in Helm charts. Let's look at how you can handle the ServiceAccount and RBAC aspects with HULL.

A word in advance: while it is useful to omit rendering of the default ServiceAccount, Role and RoleBinding objects for the most part of this tutorial it does not make sense to do this when checking the RBAC configuration options that do involve them. Therefore during this turorial section the -f ../configs/disable-default-rbac.yaml parameter is not being set and thus the default RBAC objects and ServiceAccount are rendered. For the next tutorial part add the switch again to reduce output.

Choosing ServiceAccounts for pods in HULL

When breaking down the logic within function kubernetes-dashboard.serviceAccountName and the serviceaccount.yaml, the following four variants of handling ServiceAccount configuration and naming can be deduced (in cursive the conditions that apply to each variant):

create a new individual ServiceAccount for this chart named as <release-name>-<chart-name>.

Settingwise this is done by enabling serviceAccount.create and not providing a serviceAccount.name).

This is the default in kubernetes-dashboard's values.yaml.
create a new individual ServiceAccount for this chart with a fixed provided name.

Achieved by setting serviceAccount.create to true and providing a serviceAccount.name.
use a given ServiceAccount with a fixed provided name.

For this choice set serviceAccount.create to false and provide the full serviceAccount.name to use.
use the Kubernetes default ServiceAccount simply named 'default'.

Setting serviceAccount.create to false and not supplying a serviceAccount.name has this result.

Now within HULL the ServiceAccount for a pod is derived generally by the following rules:

if no specific serviceAccountName property is set on the pod it is checked whether hull.objects.serviceaccount.default.enabled is true (defaults to true) and if so the chart and release specific default ServiceAccount is being used (which is named <release-name>-<chart-name>-default). A matching default Role and RoleBinding is also always created by default as was shown already.

This is the default in HULL's values.yaml

if a specific serviceAccountName property is set on the pod it is used for that pod. Note that this field requires the exact full name to be set. So in case you want to create and use a ServiceAccount which is dynamically created within the same chart you need to use the fullname transformation (short form _HT^) from HULL to generate this name in place. For example to configure a ServiceAccount myuser for a pod use serviceAccountName: _HT^myuser which would by default produce serviceAccountName: <release-name>-<chart-name>-myuser in the rendered output. The fullname transformation _HT^ was introduced in the last tutorial section.
lastly if the release specific default ServiceAccount is disabled, the property serviceAccountName is not set which will default in Kubernetes to using the always existing Kubernetes standard ServiceAccount simply named 'default' - don't mistake it with the chart specific default ServiceAccount HULL creates!

Using the release specific default ServiceAccount

Comparing the logic between the kubernetes-dashboard and HULL based ServiceAccount handling you can first see that the default with HULL is very similar to the default in the original chart (case 1.). The only minor difference here is that the -default suffix is added to the newly created ServiceAccount by HULL.

Using a test overlay file named ../configs/default-sa.yaml you can produce this default case. For now a roughly sketched dashboard Deployment with a basic pod spec serves to allow setting the serviceAccountName property on an actual pod.

Workloads such as the dashboard Deployment will be part of a later tutorial so you can only concentrate on the serviceAccountName property handling for now.

Insert a first simple deployment with a pod's ServiceAccount to visualize the different variants:

echo 'hull:
  objects:
    deployment:
      dashboard:
        pod:
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: "v2.5.0"' > ../configs/default-sa.yaml \
&& helm template -f ../configs/default-sa.yaml .

and you'll see the the charts default ServiceAccount being used for the pod (actually all pods if there were more and they were setup in the same way):

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        name: dashboard
        ports: []
        volumeMounts: []
      imagePullSecrets: []
      initContainers: []
      serviceAccountName: release-name-kubernetes-dashboard-default
      volumes: []

So serviceAccountName: release-name-kubernetes-dashboard-default is used for the pod by default which is as intended. The default Role and RoleBindings are auto-created and available for more detailed RBAC configuration of the default ServiceAccount in case you choose to use RBAC.

The other original cases 2. - 4. can be realized with HULL too by reconfiguring the chart at deploy time. How to do so will be examined next.

Using the Kubernetes 'default' ServiceAccount

When setting hull.objects.serviceaccount.default.enabled to false and not setting any serviceAccountName on pods, the Kubernetes standard ('default') account is used for all pods (matching original case 4.). If you don't want to have or use the default ServiceAccount at all in your applications Helm Chart but still use RBAC it makes sense to disable the default Role and RoleBindings as well so they do not point at a nonexisting ServiceAccount. Here we explicitly disable them in the upcoming examples if we don't need them for the particular example so there will be less output to interpret. Also, if you don't use RBAC at all, disabling the hull.config.specific.rbac setting will also prevent rendering of all (Cluster)Roles and (Cluster)RoleBindings.

Create a pod using the standard Kubernetes 'default' ServiceAccount like this:

echo 'hull:
  objects:
    serviceaccount: 
      default:
        enabled: false
    role: 
      default:
        enabled: false
    rolebinding: 
      default:
        enabled: false
    deployment:
      dashboard:
        pod:
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: "v2.5.0"' > ../configs/k8s-default-sa.yaml \
&& helm template -f ../configs/k8s-default-sa.yaml .

and you'll find that no default ServiceAccount, Role or RoleBinding was created and no ServiceAccount is set on the pod so the 'default' one from Kubernetes is applied as intended:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        name: dashboard
        ports: []
        volumeMounts: []
      imagePullSecrets: []
      initContainers: []
      volumes: []

Using a ServiceAccount defined outside of Helm Chart

To produce the original case 3 where an externally defined ServiceAccount is put to use, setting explicit serviceAccountName's on individual pods does the trick. It is up to you if you want to set the default ServiceAccount, Role or RoleBinding to disabled but let's do it here since we don't plan on using them elsewhere in this example and we can reduce helm template output:

echo 'hull:
  objects:
    serviceaccount: 
      default:
        enabled: false
    role: 
      default:
        enabled: false
    rolebinding: 
      default:
        enabled: false
    deployment:
      dashboard:
        pod:
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: "v2.5.0"
          serviceAccountName: my-external-cluster-sa' > ../configs/external-sa.yaml \
&& helm template -f ../configs/external-sa.yaml .

yielding the result expected:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        name: dashboard
        ports: []
        volumeMounts: []
      imagePullSecrets: []
      initContainers: []
      serviceAccountName: my-external-cluster-sa
      volumes: []

The static name for the ServiceAccount was used. If you manage ServiceAccounts outside of the particular Helm chart this is a typical scenario.

Using release specific non-default ServiceAccounts

Last case to cover is case 2. where you may want to create one or more ServiceAccounts with the Helm chart release but intend to not use the default ServiceAccount anywhere. To emulate this, setting hull.objects.serviceaccount.default.enabled to false and creating one or more ServiceAccounts for RBAC assignment with the desired names is required.

In terms of choosing the name for a ServiceAccount to be created and used in the pod spec there are two choices which are both covered by HULL. You may opt for creating ServiceAccount(s) with unique names that are release associated by dynamic naming or for creating ServiceAccount(s) with the exact names you want.

Specifying unique and non-default dynamic ServiceAccounts

To create a dynamic name (with pattern <release-name>-<chart-name>-<component-name>) it is required to apply a transformation on the serviceAccountName on the individual pods to include the dynamic prefix in the rendered result like in this example:

echo 'hull:
  objects:
    serviceaccount:
      default:
        enabled: false
      other_sa:
        automountServiceAccountToken: true
    role:
      default:
        enabled: false
    rolebinding:
      default:
        enabled: false
    deployment:
      dashboard:
        pod:
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: "v2.5.0"
          serviceAccountName: _HT^other_sa' > ../configs/internal-dynamic-sa.yaml \
&& helm template -f ../configs/internal-dynamic-sa.yaml .

_HT^ is used to create the release specific name with a given suffix (here other_sa):

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
automountServiceAccountToken: true
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: other_sa
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-other_sa
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        name: dashboard
        ports: []
        volumeMounts: []
      imagePullSecrets: []
      initContainers: []
      serviceAccountName: release-name-kubernetes-dashboard-other_sa
      volumes: []

As you can see the name of the created ServiceAccount name: release-name-kubernetes-dashboard-hull-other_sa matches the pods serviceAccountName: release-name-kubernetes-dashboard-hull-other_sa exactly as intended. In this scenario you may want to proceed defining Role and RoleBindings as required for the other_sa ServiceAccount.

Specifying non-default static ServiceAccounts

The other alternative is to create a completely static ServiceAccount name (without the <release-name>-<chart-name>- prefix) and use this for the pod(s). For this you do not need the makefullname/_HT^ transformation of the pods serviceAccountName to use the name as is but you additionally need add the staticName: true property to the ServiceAccount objects definition as in this example:

echo 'hull:
  objects:
    serviceaccount:
      default:
        enabled: false
      other_sa:
        staticName: true
        automountServiceAccountToken: true
    role:
      default:
        enabled: false
    rolebinding:
      default:
        enabled: false
    deployment:
      dashboard:
        pod:
          containers:
            dashboard:
              image:
                repository: kubernetesui/dashboard
                tag: "v2.5.0"
          serviceAccountName: other_sa' > ../configs/internal-static-sa.yaml \
&& helm template -f ../configs/internal-static-sa.yaml .

and find the statically named ServiceAccount configured for the pod:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
automountServiceAccountToken: true
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: other_sa
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: other_sa
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: dashboard
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-dashboard
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: dashboard
      app.kubernetes.io/instance: release-name
      app.kubernetes.io/name: kubernetes-dashboard
  template:
    metadata:
      annotations: {}
      labels:
        app.kubernetes.io/component: dashboard
        app.kubernetes.io/instance: release-name
        app.kubernetes.io/managed-by: Helm
        app.kubernetes.io/name: kubernetes-dashboard
        app.kubernetes.io/part-of: undefined
        app.kubernetes.io/version: 2.5.0
        helm.sh/chart: kubernetes-dashboard-5.2.0
    spec:
      containers:
      - env: []
        envFrom: []
        image: kubernetesui/dashboard:v2.5.0
        name: dashboard
        ports: []
        volumeMounts: []
      imagePullSecrets: []
      initContainers: []
      serviceAccountName: other_sa
      volumes: []

The caveat to this approach is that you need to choose carefully which ServiceAccount name and object to create because it may already exist in the namespace as opposed to sticking with dynamic names only where object names are highly unique. If you choose a static name that already exists in the namespace that will cause problems at deploy time!

Except for the default case of creating a dynamic and unique default ServiceAccount, the other ServiceAccount handling cases require little additional configuration. However, the HULL based configuration is transparent, explicit and flexible if special needs exist and the full flexibility of ServiceAccount management is needed to adapt to a given scenario. Otherwise providing pre-defined RBAC objects for the default ServiceAccount and using this ServiceAccount in the pods is likely sufficient configuration for smaller application deployments.

Defining a RoleBinding

Next up is adding more RBAC objects to the mix in form of the RoleBinding:

cat ../kubernetes-dashboard/templates/rolebinding.yaml

which is:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.create -}}
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: {{ template "kubernetes-dashboard.fullname" . }}
subjects:
  - kind: ServiceAccount
    name: {{ template "kubernetes-dashboard.serviceAccountName" . }}
    namespace: {{ .Release.Namespace }}
{{- end -}}

In HULL RBAC is globally enabled by a true/false switch which is built into HULL as a predefined key at hull.config.general.rbac. If set to true, the RBAC related objects are rendered, if set to false they are just omitted from rendering. This mimics the behaviour that is very common in many popular Helm charts and is implemented by the conditional rendering switch here:

{{ if .Values.rbac.create -}}

The recommendation is to always leave RBAC enabled in your clusters.

From the above cat output you can see that the RoleBinding and referenced Role name are again dependent on the kubernetes-dashboard.fullname function and the ServiceAccount name is subject to the kubernetes-dashboard.serviceAccountName function examined earlier. Unless you need to or want to change the controllers ServiceAccount name from the default there is nothing to do here except having RBAC enabled to create a sufficient default RoleBinding in HULL looking like this:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

If you want to deviate from the default handling you can freely overwrite the roleRef and subjects as needed, the same techniques explained above do apply for the creation of object names.

Configuring Roles

Now for the Role:

cat ../kubernetes-dashboard/templates/role.yaml

which returns:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.create -}}
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
rules:
    # Allow Dashboard to get, update and delete Dashboard exclusive secrets.
  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["kubernetes-dashboard-key-holder", "kubernetes-dashboard-certs", "kubernetes-dashboard-csrf"]
    verbs: ["get", "update", "delete"]
    # Allow Dashboard to get and update 'kubernetes-dashboard-settings' config map.
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["kubernetes-dashboard-settings"]
    verbs: ["get", "update"]
    # Allow Dashboard to get metrics.
  - apiGroups: [""]
    resources: ["services"]
    resourceNames: ["heapster", "dashboard-metrics-scraper"]
    verbs: ["proxy"]
  - apiGroups: [""]
    resources: ["services/proxy"]
    resourceNames: ["heapster", "http:heapster:", "https:heapster:", "dashboard-metrics-scraper", "http:dashboard-metrics-scraper"]
    verbs: ["get"]
{{- end -}}

You can now use the default Role that comes with HULL in the standard scenario and add the rules: as shown here and look at interesting aspects afterwards:

echo '  objects:
    role:
      default:
        rules:
          secrets:
            apiGroups:
            - ""
            resources:
            - secrets
            resourceNames: _HT![ 
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "certs") }},
              "kubernetes-dashboard-csrf",
              "kubernetes-dashboard-key-holder"
              ]
            verbs:
            - get
            - update
            - delete
          configmaps:
            apiGroups:
            - ""
            resources:
            - configmaps
            resourceNames: _HT![
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "settings") }} ]
            verbs:
            - get
            - update
          services:
            apiGroups:
            - ""
            resources:
            - services
            resourceNames:
            - "heapster"
            - "dashboard-metrics-scraper"
            verbs:
            - proxy
          services_proxy:
            apiGroups:
            - ""
            resources:
            - services/proxy
            resourceNames:
            - "heapster"
            - "http:heapster:"
            - "https:heapster:"
            - "dashboard-metrics-scraper"
            - "http:dashboard-metrics-scraper"
            verbs:
            - get' >> values.yaml

The services and services_proxy part of this configuration is static mappings to services which are defined in the metrics-server subchart, no need to focus on them now. The usage of the _HT! transformations is interesting though: utilizing the full power of the tpl function an array is dynamically created in the compact flow style [] notation and the elements are individually processed. If you remember the part where the Secrets where created there was one with a dynamic name (certs) and two where a static name was demanded (csrf and key-holder). Therefore you can see in the above specification that the dynamic names are created using the hull.metadata.fullname function being called within the _HT! tpl transformation.

The hull.metadata.fullname is also what is called internally when using the HULL transformation hull.util.transformation.makefullname/_HT^. Here you need to use it directly within the tpl function which is however also straightforward since it has a fixed signature of:

include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "<COMPONENT>")

and you only need to set the <COMPONENT> part to the objects key you are referring to.

As a side note on the original template: be aware that the fact that the certs Secrets name is refered to as kubernetes-dashboard-certs - a static expression - with:

  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["kubernetes-dashboard-key-holder", "kubernetes-dashboard-certs", "kubernetes-dashboard-csrf"]

is problematic. Looking back at the name specification of the cert Secret:

  name: {{ template "kubernetes-dashboard.fullname" . }}-certs

there is actually no guarantee that the Secrets name is constructed like this. Depending on overall chart configuration (fullnameOverride) the static reference to a dynamic name may be invalid and not point to the correct name of the certs Secret. So this is a "bug" in the sense that it can lead to a potentially unusable release. Due to the huge amount of manual template creation in the regular Helm workflow problems such as these arise often where different parts of the templates with overlapping concerns are not properly matched or updated together.

Note that with the HULL object and reference handling this would not happen here since name generation (the object instance name and the reference name) is handled via the same hull.metadata.fullname function so the reference is always a stable one.

Finally if you print the output of above:

helm template .

and review whether the desired outcome was rendered:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules:
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-settings
  resources:
  - configmaps
  verbs:
  - get
  - update
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-certs
  - kubernetes-dashboard-csrf
  - kubernetes-dashboard-key-holder
  resources:
  - secrets
  verbs:
  - get
  - update
  - delete
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - dashboard-metrics-scraper
  resources:
  - services
  verbs:
  - proxy
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - 'http:heapster:'
  - 'https:heapster:'
  - dashboard-metrics-scraper
  - http:dashboard-metrics-scraper
  resources:
  - services/proxy
  verbs:
  - get
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

everything should be as intended.

On to the last aspect of this tutorial part, the cluster-level RBAC objects!

Writing ClusterRole and ClusterRoleBindings

Structurally ClusterRole and ClusterRoleBinding objects are nearly identical to their "non-prefixed with Cluster" counterparts.

ClusterRoles

For the ClusterRole/Role difference the Kubernetes documentation states:

A Role always sets permissions within a particular namespace; when you create a Role, you have to specify the namespace it belongs in.

ClusterRole, by contrast, is a non-namespaced resource. The resources have different names (Role and ClusterRole) because a Kubernetes object always has to be either namespaced or not namespaced; it can't be both.

Furthermore ClusterRole has an additional property aggregationRule which the Role object does not have.

ClusterRoleBinding

For the ClusterRoleBinding the roleRef needs to reference a global ClusterRole and not a Role.

Converting the existing Cluster-scope RBAC objects

Recaping the Cluster based RBAC objects:

find ../kubernetes-dashboard/templates -type f -iregex '.*\(ClusterRole\|\clusterrole\).*' | sort

you can see they fall into two "groups", the metrics and readonly objects:

../kubernetes-dashboard/templates/clusterrole-metrics.yaml
../kubernetes-dashboard/templates/clusterrole-readonly.yaml
../kubernetes-dashboard/templates/clusterrolebinding-metrics.yaml
../kubernetes-dashboard/templates/clusterrolebinding-readonly.yaml

First convert the readonly objects from the /templates folder, starting with the ClusterRole:

cat ../kubernetes-dashboard/templates/clusterrole-readonly.yaml

showing:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.clusterReadOnlyRole -}}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: "{{ template "kubernetes-dashboard.fullname" . }}-readonly"
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
rules:
  - apiGroups:
      - ""
    resources:
      - configmaps
      - endpoints
      - persistentvolumeclaims
      - pods
      - replicationcontrollers
      - replicationcontrollers/scale
      - serviceaccounts
      - services
      - nodes
      - persistentvolumeclaims
      - persistentvolumes
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - ""
    resources:
      - bindings
      - events
      - limitranges
      - namespaces/status
      - pods/log
      - pods/status
      - replicationcontrollers/status
      - resourcequotas
      - resourcequotas/status
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - ""
    resources:
      - namespaces
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - apps
    resources:
      - daemonsets
      - deployments
      - deployments/scale
      - replicasets
      - replicasets/scale
      - statefulsets
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - autoscaling
    resources:
      - horizontalpodautoscalers
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - batch
    resources:
      - cronjobs
      - jobs
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
    resources:
      - daemonsets
      - deployments
      - deployments/scale
      - ingresses
      - networkpolicies
      - replicasets
      - replicasets/scale
      - replicationcontrollers/scale
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - policy
    resources:
      - poddisruptionbudgets
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - networking.k8s.io
    resources:
      - networkpolicies
      - ingresses
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - storage.k8s.io
    resources:
      - storageclasses
      - volumeattachments
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - rbac.authorization.k8s.io
    resources:
      - clusterrolebindings
      - clusterroles
      - roles
      - rolebindings
    verbs:
      - get
      - list
      - watch
{{- end -}}

The whole ClusterRole is only rendered given that .Values.rbac.clusterReadOnlyRole is true, looking at it:

cat ../kubernetes-dashboard/values.yaml | grep "clusterReadOnlyRole" -B 13 -A 1

it comes with following description:


rbac:
  # Specifies whether namespaced RBAC resources (Role, Rolebinding) should be created
  create: true

  # Specifies whether cluster-wide RBAC resources (ClusterRole, ClusterRolebinding) to access metrics should be created
  # Independent from rbac.create parameter.
  clusterRoleMetrics: true

  # Start in ReadOnly mode.
  # Specifies whether cluster-wide RBAC resources (ClusterRole, ClusterRolebinding) with read only permissions to all resources listed inside the cluster should be created
  # Only dashboard-related Secrets and ConfigMaps will still be available for writing.
  #
  # The basic idea of the clusterReadOnlyRole
  # is not to hide all the secrets and sensitive data but more
  # to avoid accidental changes in the cluster outside the standard CI/CD.
  #
  # It is NOT RECOMMENDED to use this version in production.
  # Instead you should review the role and remove all potentially sensitive parts such as
  # access to persistentvolumes, pods/log etc.
  #
  # Independent from rbac.create parameter.
  clusterReadOnlyRole: false

As expected, when checking the ClusterRoleBinding:

cat ../kubernetes-dashboard/templates/clusterrolebinding-readonly.yaml

the same {{ if .Values.rbac.clusterReadOnlyRole -}} condition applies:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.clusterReadOnlyRole -}}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: {{ template "kubernetes-dashboard.fullname" . }}-readonly
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: {{ template "kubernetes-dashboard.fullname" . }}-readonly
subjects:
  - kind: ServiceAccount
    name: {{ template "kubernetes-dashboard.serviceAccountName" . }}
    namespace: {{ .Release.Namespace }}
{{- end }}

Thus it makes much sense to model the rbac.clusterReadOnlyRole switch in our hull.config.specific section so we can centrally disable and enable it. Otherwise nothing new or unexpected happens here so it is straightforward to convert this to a HULL based chart logic but before that check on the metrics components.

Inspecting the metrics components you see that they behave the same way: rendering is controlled by a global switch {{ if .Values.rbac.clusterRoleMetrics -}} which is also contained in the last cat of values.yaml and the rest is similar mapping of rules to the ClusterRole and ClusterRoleBinding between the ClusterRole and the ServiceAccount:

cat ../kubernetes-dashboard/templates/clusterrole-metrics.yaml

gives:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.clusterRoleMetrics -}}
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: "{{ template "kubernetes-dashboard.fullname" . }}-metrics"
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
rules:
  # Allow Metrics Scraper to get metrics from the Metrics server
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods", "nodes"]
    verbs: ["get", "list", "watch"]
{{- end }}

and:

cat ../kubernetes-dashboard/templates/clusterrolebinding-metrics.yaml

gives:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{ if .Values.rbac.clusterRoleMetrics -}}
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: "{{ template "kubernetes-dashboard.fullname" . }}-metrics"
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: {{ template "kubernetes-dashboard.fullname" . }}-metrics
subjects:
  - kind: ServiceAccount
    name: {{ template "kubernetes-dashboard.serviceAccountName" . }}
    namespace: {{ .Release.Namespace }}
{{- end }}

In terms of converting this, first add in the new "global/specific" rbac.clusterReadOnlyRole and rbac.clusterRoleMetrics parameters to our hull.config.specific section:

sed '/^\s\s\s\sspecific/r'<(
      echo "      rbac:"
      echo "        clusterReadOnlyRole: false"
      echo "        clusterRoleMetrics: true"
    ) -i -- values.yaml

and then add the readonly ClusterRole and ClusterRoleBinding with the enabled switch bound to the clusterReadOnlyRole condition and the metrics ClusterRole and ClusterRoleBinding with the enabled switch bound to the clusterRoleMetrics condition:

echo '    clusterrole:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        rules:
          cluster_objects:
            apiGroups:
            - ""
            resources:
            - configmaps
            - endpoints
            - persistentvolumeclaims
            - pods
            - replicationcontrollers
            - replicationcontrollers/scale
            - serviceaccounts
            - services
            - nodes
            - persistentvolumeclaims
            - persistentvolumes
            verbs:
            - get
            - list
            - watch
          statuses:
            apiGroups:
            - ""
            resources:
            - bindings
            - events
            - limitranges
            - namespaces/status
            - pods/log
            - pods/status
            - replicationcontrollers/status
            - resourcequotas
            - resourcequotas/status
            verbs:
            - get
            - list
            - watch
          namespaces:
            apiGroups:
            - ""
            resources:
            - namespaces
            verbs:
            - get
            - list
            - watch
          apps:
            apiGroups:
            - apps
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - replicasets
            - replicasets/scale
            - statefulsets
            verbs:
            - get
            - list
            - watch
          autoscaling:
            apiGroups:
            - autoscaling
            resources:
            - horizontalpodautoscalers
            verbs:
            - get
            - list
            - watch
          jobs:
            apiGroups:
            - batch
            resources:
            - cronjobs
            - jobs
            verbs:
            - get
            - list
            - watch
          extensions:
            apiGroups:
            - extensions
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - ingresses
            - networkpolicies
            - replicasets
            - replicasets/scale
            - replicationcontrollers/scale
            verbs:
            - get
            - list
            - watch
          pdb:
            apiGroups:
            - policy
            resources:
            - poddisruptionbudgets
            verbs:
            - get
            - list
            - watch
          network:
            apiGroups:
            - networking.k8s.io
            resources:
            - networkpolicies
            - ingresses
            verbs:
            - get
            - list
            - watch
          storage:
            apiGroups:
            - storage.k8s.io
            resources:
            - storageclasses
            - volumeattachments
            verbs:
            - get
            - list
            - watch
          rbac:
            apiGroups:
            - rbac.authorization.k8s.io
            resources:
            - clusterrolebindings
            - clusterroles
            - roles
            - rolebindings
            verbs:
            - get
            - list
            - watch
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        rules:
          metrics:
            apiGroups:
            - "metrics.k8s.io"
            resources:
            - pods
            - nodes
            verbs:
            - get
            - list
            - watch
    clusterrolebinding:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^readonly
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^metrics
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default' >> values.yaml

If you want to check the new objects out, you can enable them both:

echo 'hull:
  config:
    specific:
      rbac:
        clusterReadOnlyRole: true' > ../configs/enable-cluster-role.yaml \
&& helm template -f ../configs/enable-cluster-role.yaml .

and examine it:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: metrics
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-metrics
  namespace: ""
rules:
- apiGroups:
  - metrics.k8s.io
  resources:
  - pods
  - nodes
  verbs:
  - get
  - list
  - watch
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: readonly
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-readonly
  namespace: ""
rules:
- apiGroups:
  - apps
  resources:
  - daemonsets
  - deployments
  - deployments/scale
  - replicasets
  - replicasets/scale
  - statefulsets
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - autoscaling
  resources:
  - horizontalpodautoscalers
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - ""
  resources:
  - configmaps
  - endpoints
  - persistentvolumeclaims
  - pods
  - replicationcontrollers
  - replicationcontrollers/scale
  - serviceaccounts
  - services
  - nodes
  - persistentvolumeclaims
  - persistentvolumes
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - extensions
  resources:
  - daemonsets
  - deployments
  - deployments/scale
  - ingresses
  - networkpolicies
  - replicasets
  - replicasets/scale
  - replicationcontrollers/scale
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - batch
  resources:
  - cronjobs
  - jobs
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - ""
  resources:
  - namespaces
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - networking.k8s.io
  resources:
  - networkpolicies
  - ingresses
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - policy
  resources:
  - poddisruptionbudgets
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - rbac.authorization.k8s.io
  resources:
  - clusterrolebindings
  - clusterroles
  - roles
  - rolebindings
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - ""
  resources:
  - bindings
  - events
  - limitranges
  - namespaces/status
  - pods/log
  - pods/status
  - replicationcontrollers/status
  - resourcequotas
  - resourcequotas/status
  verbs:
  - get
  - list
  - watch
- apiGroups:
  - storage.k8s.io
  resources:
  - storageclasses
  - volumeattachments
  verbs:
  - get
  - list
  - watch
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: metrics
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-metrics
  namespace: ""
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: release-name-kubernetes-dashboard-metrics
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
  namespace: default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: readonly
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-readonly
  namespace: ""
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: release-name-kubernetes-dashboard-readonly
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
  namespace: default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules:
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-settings
  resources:
  - configmaps
  verbs:
  - get
  - update
- apiGroups:
  - ""
  resourceNames:
  - release-name-kubernetes-dashboard-certs
  - kubernetes-dashboard-csrf
  - kubernetes-dashboard-key-holder
  resources:
  - secrets
  verbs:
  - get
  - update
  - delete
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - dashboard-metrics-scraper
  resources:
  - services
  verbs:
  - proxy
- apiGroups:
  - ""
  resourceNames:
  - heapster
  - 'http:heapster:'
  - 'https:heapster:'
  - dashboard-metrics-scraper
  - http:dashboard-metrics-scraper
  resources:
  - services/proxy
  verbs:
  - get
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

Wrap up

That is almost it for this tutorial part. If you want to compare the intended outcome with what you created, your values.yaml should look like this at this point:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      rbac:
        clusterReadOnlyRole: false
        clusterRoleMetrics: true
      settings: {}
      pinnedCRDs: {}
  objects:
    role:
      default:
        rules:
          secrets:
            apiGroups:
            - ""
            resources:
            - secrets
            resourceNames: _HT![
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "certs") }},
              "kubernetes-dashboard-csrf",
              "kubernetes-dashboard-key-holder"
              ]
            verbs:
            - get
            - update
            - delete
          configmaps:
            apiGroups:
            - ""
            resources:
            - configmaps
            resourceNames: _HT![
              {{ include "hull.metadata.fullname" (dict "PARENT_CONTEXT" (index . "$") "COMPONENT" "settings") }} ]
            verbs:
            - get
            - update
          services:
            apiGroups:
            - ""
            resources:
            - services
            resourceNames:
            - "heapster"
            - "dashboard-metrics-scraper"
            verbs:
            - proxy
          services_proxy:
            apiGroups:
            - ""
            resources:
            - services/proxy
            resourceNames:
            - "heapster"
            - "http:heapster:"
            - "https:heapster:"
            - "dashboard-metrics-scraper"
            - "http:dashboard-metrics-scraper"
            verbs:
            - get
    clusterrole:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        rules:
          cluster_objects:
            apiGroups:
            - ""
            resources:
            - configmaps
            - endpoints
            - persistentvolumeclaims
            - pods
            - replicationcontrollers
            - replicationcontrollers/scale
            - serviceaccounts
            - services
            - nodes
            - persistentvolumeclaims
            - persistentvolumes
            verbs:
            - get
            - list
            - watch
          statuses:
            apiGroups:
            - ""
            resources:
            - bindings
            - events
            - limitranges
            - namespaces/status
            - pods/log
            - pods/status
            - replicationcontrollers/status
            - resourcequotas
            - resourcequotas/status
            verbs:
            - get
            - list
            - watch
          namespaces:
            apiGroups:
            - ""
            resources:
            - namespaces
            verbs:
            - get
            - list
            - watch
          apps:
            apiGroups:
            - apps
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - replicasets
            - replicasets/scale
            - statefulsets
            verbs:
            - get
            - list
            - watch
          autoscaling:
            apiGroups:
            - autoscaling
            resources:
            - horizontalpodautoscalers
            verbs:
            - get
            - list
            - watch
          jobs:
            apiGroups:
            - batch
            resources:
            - cronjobs
            - jobs
            verbs:
            - get
            - list
            - watch
          extensions:
            apiGroups:
            - extensions
            resources:
            - daemonsets
            - deployments
            - deployments/scale
            - ingresses
            - networkpolicies
            - replicasets
            - replicasets/scale
            - replicationcontrollers/scale
            verbs:
            - get
            - list
            - watch
          pdb:
            apiGroups:
            - policy
            resources:
            - poddisruptionbudgets
            verbs:
            - get
            - list
            - watch
          network:
            apiGroups:
            - networking.k8s.io
            resources:
            - networkpolicies
            - ingresses
            verbs:
            - get
            - list
            - watch
          storage:
            apiGroups:
            - storage.k8s.io
            resources:
            - storageclasses
            - volumeattachments
            verbs:
            - get
            - list
            - watch
          rbac:
            apiGroups:
            - rbac.authorization.k8s.io
            resources:
            - clusterrolebindings
            - clusterroles
            - roles
            - rolebindings
            verbs:
            - get
            - list
            - watch
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        rules:
          metrics:
            apiGroups:
            - "metrics.k8s.io"
            resources:
            - pods
            - nodes
            verbs:
            - get
            - list
            - watch
    clusterrolebinding:
      readonly:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterReadOnlyRole
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^readonly
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default
      metrics:
        enabled: _HT?(index . "$").Values.hull.config.specific.rbac.clusterRoleMetrics
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: ClusterRole
          name: _HT^metrics
        subjects:
        - namespace: _HT!{{ (index . "$").Release.Namespace }}
          kind: ServiceAccount
          name: _HT^default

Backup your finished values.yaml to the values.tutorial-part.yaml in case you want to modify, play around or start from scratch again with the values.yaml:

cp values.yaml values.tutorial-part.yaml

Lastly, we combine our previous results with the newly written ones. For this add the intermediate results to the values.full.yaml. Since we copied the hull.config.specific part in the beginning of this tutorial part we can just overwrite it with the one we expanded upon during this tutorial part. But the already existing hull.objects need to be merged with the newly defined ones so you can copy them first from values.full.yaml before appending them to the values.yaml content and saving the complete result as values.full.yaml again:

sed '1,/objects:/d' values.full.yaml > _tmp && cp values.yaml values.full.yaml && cat _tmp >> values.full.yaml && rm _tmp

The result of this course can be downloaded here for reference.

See you on the next part of this series hopefully where you take a close look at defining workload objects via HULL. Thanks for reading!

HULL Tutorial 03: Integrating ConfigMaps and Secrets

gre9ory — Tue, 31 May 2022 11:24:38 +0000

Preparation

As a reminder, the goal of this tutorial series is to demonstrate how to build Helm charts based on the HULL library chart by recreating the functionality of the original kubernetes-dashboard Helm chart with a HULL based chart from scratch. When you have followed the previous part of this tutorial on setting up a HULL base chart you have created a for now unconfigured Helm chart named kubernetes-dashboard-hull in the 02_setup subfolder of your working directory (we assume that's ~/kubernetes-dashboard-hull here). You can alternatively download the current chart state here and continue from there. Also you should have checked out and extracted the kubernetes-dashboard Helm chart to kubernetes-dashboard in your working directory because examining it will be frequently required.

Start by inspecting the current state of the project with:

cd ~/kubernetes-dashboard-hull && ls 02_setup/kubernetes-dashboard*

which should be giving you:

02_setup/kubernetes-dashboard:
Chart.lock  Chart.yaml  README.md  charts  templates  values.yaml

02_setup/kubernetes-dashboard-hull:
Chart.lock  Chart.yaml  charts  templates  values.yaml

To continue you should make a copy for our new tutorial Part and leave the current state result untouched:

cp -R 02_setup/ 03_configmaps_and_secrets

Ok, now you can change to our freshly copied kubernetes-dashboard-hull chart directory:

cd 03_configmaps_and_secrets/kubernetes-dashboard-hull

and start adding things to our Helm chart!

Analyzing the existing ConfigMaps

It is time to start moving the objects from the original to our new chart and focus on ConfigMaps and Secrets as a first step.

When checking the kubernetes-dashboard's templates folder with:

find ../kubernetes-dashboard/templates -type f -iregex '.*\(configmap\|secret\).*' | sort

you can spot one ConfigMap and one Secret file each in there from the response:

../kubernetes-dashboard/templates/configmap.yaml
../kubernetes-dashboard/templates/secret.yaml

Note that file naming of templates does not actually mean anything in terms of what may be contained in them but for our exercise the result above points in the right direction.

You can proceed with getting the contents of the templates/configmap.yaml ConfigMap:

cat ../kubernetes-dashboard/templates/configmap.yaml

shows this:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
  name: kubernetes-dashboard-settings
data:
{{- with .Values.settings }}
  _global: {{ toJson . | quote }}
{{- end }}
{{- with .Values.pinnedCRDs }}
  _pinnedCRD: {{ toJson . | quote }}
{{- end }}

Starting from the top, first you can see that some labels are generated by an include of kubernetes-dashboard.labels helper function. In classic Helm charts such helper functions are found usually in one or more _*.tpl helper files. The intention of the leading underscore in the name and the .tpl ending is to indicate these files do not contain objects that can be rendered but only helper functions.

To get an overview of the helper functions you may display the _*.tpl file contents because we will need to get back to them frequently. Cat the files contents with:

cat ../kubernetes-dashboard/templates/_*.tpl

to print the helper functions which are for the most part the typical assortment of a Helm charts helper functions:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{/* vim: set filetype=mustache: */}}
{{/*
Expand the name of the chart.
*/}}
{{- define "kubernetes-dashboard.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).
If release name contains chart name it will be used as a full name.
*/}}
{{- define "kubernetes-dashboard.fullname" -}}
{{- if .Values.fullnameOverride -}}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- $name := default .Chart.Name .Values.nameOverride -}}
{{- if contains $name .Release.Name -}}
{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
{{- else -}}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
{{- end -}}
{{- end -}}
{{- end -}}

{{/*
Create chart name and version as used by the chart label.
*/}}
{{- define "kubernetes-dashboard.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{/*
Common labels
*/}}
{{- define "kubernetes-dashboard.labels" -}}
app.kubernetes.io/name: {{ include "kubernetes-dashboard.name" . }}
helm.sh/chart: {{ include "kubernetes-dashboard.chart" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}

{{/*
Common label selectors
*/}}
{{- define "kubernetes-dashboard.matchLabels" -}}
app.kubernetes.io/name: {{ include "kubernetes-dashboard.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

{{/*
Name of the service account to use
*/}}
{{- define "kubernetes-dashboard.serviceAccountName" -}}
{{- if .Values.serviceAccount.create -}}
    {{ default (include "kubernetes-dashboard.fullname" .) .Values.serviceAccount.name }}
{{- else -}}
    {{ default "default" .Values.serviceAccount.name }}
{{- end -}}
{{- end -}}
# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{/* vim: set filetype=mustache: */}}
{{/*
Renders a value that contains template.
Usage:
{{ include "common.tplvalues.render" ( dict "value" .Values.path.to.the.Value "context" $) }}
*/}}
{{- define "common.tplvalues.render" -}}
    {{- if typeIs "string" .value }}
        {{- tpl .value .context }}
    {{- else }}
        {{- tpl (.value | toYaml) .context }}
    {{- end }}
{{- end -}}

As already demonstrated in the previous part of this tutorial series, all HULL-created objects do automatically get the standard Kubernetes metadata fields populated. There is no further necessity to work on the standard metadata of our objects for the conversion, HULL automatically creates metadata information that is equivalent to what happens in the kubernetes-dashboard.labels function that is part of every objects metadata label definition:

{{/*
Common labels
*/}}
{{- define "kubernetes-dashboard.labels" -}}
app.kubernetes.io/name: {{ include "kubernetes-dashboard.name" . }}
helm.sh/chart: {{ include "kubernetes-dashboard.chart" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}

So that is covered. After the standard labels have been set here:

    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}

there comes an optional block where additional common labels may be set:

    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}

The definition of common.tplvalues.render can be found above where you checked the helper functions, anyway here it is again:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

{{/* vim: set filetype=mustache: */}}
{{/*
Renders a value that contains template.
Usage:
{{ include "common.tplvalues.render" ( dict "value" .Values.path.to.the.Value "context" $) }}
*/}}
{{- define "common.tplvalues.render" -}}
    {{- if typeIs "string" .value }}
        {{- tpl .value .context }}
    {{- else }}
        {{- tpl (.value | toYaml) .context }}
    {{- end }}
{{- end -}}

What happens here is pretty simple actually: when a string is passed as value the value is subjected to the tpl function, for anything else (dictionaries, arrays) the Go object is converted to a YAML block before being subjected to tpl.

At this point you may check the reference to .Values.commonLabels which is defined in the values.yaml with cat and a little context around the hits:

cat ../kubernetes-dashboard/values.yaml | grep "commonLabels" -B 1 -A 4

which reveals:


## @param commonLabels Labels to add to all deployed objects
##
commonLabels: {}
## @param commonAnnotations Annotations to add to all deployed objects
##
commonAnnotations: {}

So with all pieces put together, with commonLabels being a dictionary the function would insert any key value pairs that may be defined in commonLabels into the labels section of the ConfigMap. With HULL, further metadata such as the commonLabels here can be added at the global level, the object type level or at object instance level. You will see this in use in a minute.

In terms of the annotations it is the same procedure here with the commonAnnotations as with the commonLabels so no need to check this any closer.

Now focus on the ConfigMaps data section:

data:
{{- with .Values.settings }}
  _global: {{ toJson . | quote }}
{{- end }}
{{- with .Values.pinnedCRDs }}
  _pinnedCRD: {{ toJson . | quote }}
{{- end }}

For storing the _global and _pinnedCRD data into the ConfigMap the YAML based data from the values.yaml fields .Values.settings and .Values.pinnedCRDs is converted to JSON. How to achieve that with HULL and without any templates is what will be explored next. This wraps up the inspection of this ConfigMap and the conversion to a HULL specification can begin.

Creating ConfigMaps with HULL

Time to get down to business by creating the first (and in our case only) ConfigMap in the HULL charts values.yaml.

So to get started, copy or type in the following:

echo 'hull:
  objects:
    configmap:
      settings:
        data:
          _global:
            inline: ""
          _pinnedCRD:
            inline: ""' >> values.yaml

to create the ConfigMap with empty entries in values.yaml. You can check the initial output with:

helm template .

now containing the settings ConfigMap:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

Right now the settings ConfigMaps data entries are intentionally just empty, this is the relevant excerpt from above output:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings

Before dealing with the proper population of the data entries as JSON content a brief detour for covering the built-in HULL metadata features is useful.

Adding Metdata to objects globally, on object type and object level

Say you want to add more metadata to your objects. For instance you may want to add further labels or annotations to all your objects (the commonLabels and commonAnnotations from the original chart) or only some of them. Maybe all ConfigMaps should have a particular metadata label or annotation. Or there is a set of custom metadata labels you want to associate on objects of different types which are to be grouped in some sense? All of this can be done conveniently with HULL!

To start testing out configurational variations to the current values.yaml or enabling/disabling features it is time to bring in another (familiar) layer of configuration that enables performing our tests of the functionality and simulate system specific settings in addition to the values.yaml defaults. An 'external' or 'system specific' values.yaml' is required to vary the configuration on top of the defaults and see the effect on rendering outputs. Before any HULL related processing takes place, the contents of this external file are simply overlayed or merged entry by entry with the values.yaml structure when applied with -f <file-path> to any helm command. Note that any data that is added via the -f switch has precedence over the values.yaml defaults (which is what you'd expect anyways).

Start by creating a new ../configs folder now to hold such 'external configurations' to be applied on top of our default values.yaml:

mkdir ../configs

Add a first test configuration like this by adding sample labels to our ConfigMap and default object instances. First you write the overlay data for our test and then overlay it when helm templateing it:

echo 'hull:
  config:
    general:
      metadata:
        labels:
          custom:
            label1: hello
            label2: global
            label3: labels!'> ../configs/global-custom-metadata.yaml\
&& helm template -f ../configs/global-custom-metadata.yaml .

and all objects have the shared labels attached as you can see from the output:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: global
    label3: labels!
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: global
    label3: labels!
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: global
    label3: labels!
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: global
    label3: labels!
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

If you'd want the labels only being attached to ConfigMap objects you can attach them to the HULL internal default ConfigMap object. All object types you can use in HULL support having a special default object (specified with key _HULL_OBJECT_TYPE_DEFAULT_) where you can attach default fields and values that are being inherited by all instances of that type. Individual instances may in turn overwrite them again specifically. Instances of _HULL_OBJECT_TYPE_DEFAULT_ objects are of course never rendered, they only provide templates with default values for instances of the parent objects type.

In practice create another test configuration to test objecttype level metadata population:

echo 'hull:
  objects:
    configmap:
      _HULL_OBJECT_TYPE_DEFAULT_:
        labels:
          label1: hello
          label2: objecttype
          label3: labels!
      another:
        data: {}
      and_another:
        data: {}'> ../configs/objecttype-custom-metadata.yaml \
&& helm template -f ../configs/objecttype-custom-metadata.yaml .

you can see that only the three specified ConfigMaps have the labels assigned now:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: and_another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-and_another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

It is important to mention that object type defaults do not only apply to metadata, you can basically default any property value on the object definition with a value, for example to predefine a data entry that all ConfigMaps should have you could do the following:

echo 'hull:
  objects:
    configmap:
      _HULL_OBJECT_TYPE_DEFAULT_:
        labels:
          label1: hello
          label2: objecttype
          label3: labels!
        data:
          see:
            inline: "I am in every ConfigMap!"
      another:
        data: {}
      and_another:
        data: {}'> ../configs/objecttype-data-default.yaml \
&& helm template -f ../configs/objecttype-data-default.yaml .

and see it actually is in every ConfigMap:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  see: I am in every ConfigMap!
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: and_another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-and_another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  see: I am in every ConfigMap!
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
  see: I am in every ConfigMap!
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

Adding a dedicated label or annotation just to your settings ConfigMap is easy with this overlay configuration for example:

echo 'hull:
  objects:
    configmap:
      _HULL_OBJECT_TYPE_DEFAULT_:
        labels:
          label1: hello
          label2: objecttype
          label3: labels!
      settings:
        labels:
          label4: I am a settings label!
        annotations:
          annotation: I am a settings annotation!
      another:
        data: {}
      and_another:
        data: {}'> ../configs/object-custom-metadata.yaml \
&& helm template -f ../configs/object-custom-metadata.yaml .

yielding added annotation on the settings ConfigMap:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: and_another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-and_another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: another
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
  name: release-name-kubernetes-dashboard-another
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: ""
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations:
    annotation: I am a settings annotation!
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
    label1: hello
    label2: objecttype
    label3: labels!
    label4: I am a settings label!
  name: release-name-kubernetes-dashboard-settings
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

As you already saw, HULL automatically creates a RBAC trinity of default ServiceAccount, Role and RoleBinding which can be put to use straight away and you saw how setting metadata on different hierarchical levels affected these object instances. However since there is gonna be a lot more of helm template . output to examine in the next tutorial parts it is recommended to turn off rendering the default RBAC instances and the ServiceAccount when it is not of concern. Using an overlay values.yaml like this one:

echo 'hull:
  objects:
    serviceaccount:
      default:
        enabled: false
    role:
      default:
        enabled: false
    rolebinding:
      default:
        enabled: false'> ../configs/disable-default-rbac.yaml

is a good approach to disable the RBAC objects whenever they are not of interest. Whenever it is relevant for the topic of the tutorial however you can just switch RBAC objects on again and simply omit the -f ../configs/disable-default-rbac.yaml overlay.

In the next part the focus is on populating the data section. For this we need to introduce a way to dynamically change the provided YAML contents to JSON while rendering. When explicitly not using any templates the question is how can you process the values.yaml contents dynamically before rendering?

With HULL transformations you can. They provide the answer to this problem and they will be used wherever the need arises to model dynamic behavior for improving user experience.

Using HULL transformations

In the regular Helm workflow any templating expressions or other dynamic behavior is not tolerated within the values.yaml itself since it must at all times conform to the YAML specification. Templating expressions are only allowed and evaluated in the templates folder.

The focus and main goal of creating HULL was to get rid of the need to model each simple 1:1 projection from values.yaml properties to Kubernetes object properties by providing direct access to all Kubernetes objects properties instead to only having to specify exactly what you want. This is solely achieved by configuration of the values.yaml and without any chart-specific custom templates in the template folder. Transformations in HULL put back the possibility to use template expressions for more complex projections which are driven from the values.yaml alone. But how is this done when Helm prohibits any templating expression in the values.yaml?

Since within the HULL processing pipeline the whole values.yaml tree is traversed internally it enables the possibility to inject templating again into property value calculation by processing keywords that signal the use of a dynamic function (=transformation) and its parameters. The return value of the transformation then replaces the property value where the transformation was called. A caveat is that the specification and use of those functions must not invalidate the YAML (and JSON schema) of the values.yaml, otherwise Helm would not be happy about processing the values.yaml. For this reason the transformations themselves are wrapped as strings, dictionaries or arrays.

For HULL to know that a property value requires transforming, special transformation triggers/keyword prefixes (_HULL_TRANSFORMATION_ or any existing short forms of specific transformations such as _HT?, _HT!, _HT*, _HT^ and _HT&) signal the use of a transformation to determine the actual value to be rendered. More information about transformations and how to specify and use them can be found in the HULL docs on transformations but they are explored and utilized in this tutorial to a large degree to learn how to use them.

The `_HT?` transformation

The _HT? (or in long form hull.util.transformation.bool function) is a first simple transformation example albeit a useful one. It needs a templating expression as input which needs to resolve to a boolean value when computed. It can therefore be used to set any boolean property but it is mainly useful to determine whether a particular object should be rendered or not at deploy time depending on automated conditions. Rendering for all HULL objects is controlled via the boolean enabled property on the object instance, you can set it for each main object defined through HULL. By binding the enabled property's value to an arbitrary hull.util.transformation.bool function returning a boolean value you can dynamically enable and disable rendering of the object depending on other configurational input to your chart.

To highlight the usage of transformations such as the _HT?, say for demo purposes you only want to render the settings ConfigMap in case its _global or _pinnedCRD entry has any content (meaning the inline property is not equal to an empty string). A built-in hull.util.transformation.bool transformation to be bound to the ConfigMaps enabled switch could look like this:

enabled: _HULL_TRANSFORMATION_<<<NAME=hull.util.transformation.bool>>><<<CONDITION=or (ne (index . "$").Values.hull.objects.configmap.settings.data._global.inline "") (ne (index . "$").Values.hull.objects.configmap.settings.data._pinnedCRD.inline "")>>>

wherein you check that any of the _global.inline or the _pinnedCRD data section is not empty and only then render the ConfigMap. You can see that it is possible to use the well-known Go templating functionalities here, the only thing to keep in mind is that you cannot use the global . context (as in .Values.someProperty) but must use the expression (index . "$") instead to access the global context (as in (index . "$").Values.someProperty).

To really save some typing in the future you should use the short form to built-in transformations. They can be viewed as a kind of macro that points to a specifc transformation and omit the argument naming because the transformation only has one argument whose value is supplied directly after the shortcut.

The same transformation as above in short form looks like this:

enabled: _HT?or (ne (index . "$").Values.hull.objects.configmap.settings.data._global.inline "") (ne (index . "$").Values.hull.objects.configmap.settings.data._pinnedCRD.inline "")

which minifies the call to the transformation and is way handier to type. Again please checkout the HULL docs on transformations for more information.

Now test this out with a test config file:

echo 'hull:
  objects:
    configmap:
      settings:
        enabled: _HT?or (ne (index . "$").Values.hull.objects.configmap.settings.data._global.inline "") (ne (index . "$").Values.hull.objects.configmap.settings.data._pinnedCRD.inline "")'> ../configs/bool-transformation-1.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/bool-transformation-1.yaml .

and see that the settings ConfigMap is not rendered:

Since the default RBAC objects are also omitted via -f ../configs/disable-default-rbac.yaml the output is just empty.

For the counter example, add some content to the _global entry:

echo 'hull:
  objects:
    configmap:
      settings:
        enabled: _HT?or (ne (index . "$").Values.hull.objects.configmap.settings.data._global.inline "") (ne (index . "$").Values.hull.objects.configmap.settings.data._pinnedCRD.inline "")
        data:
          _global:
            inline: "test"'> ../configs/bool-transformation-2.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/bool-transformation-2.yaml .

observe the ConfigMap back again in the output:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: test
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings

After this detour introducing the hull.util.transformation.bool/_HT? transformation in practice you can focus again on the transformation to JSON part.

Recap the data section of the ConfigMap you want to convert:

data:
{{- with .Values.settings }}
  _global: {{ toJson . | quote }}
{{- end }}
{{- with .Values.pinnedCRDs }}
  _pinnedCRD: {{ toJson . | quote }}
{{- end }}

You can see there is a redirection to the source of the entries values (.Values.settings and .Values.pinnedCRDs) where the data is defined and processed here in the template. To mimic this you need to add a similar redirection within values.yaml from which data is being read when processing _global and _pinnedCRD and then a function to convert it on rendering.

A similar use case is when individual properties are logically referenced in multiple places (1:n relations) within values.yaml it is best to define the actual data in a 'single source of truth' fashion, like it is done in the original Helm chart concept with the .Values.settings and .Values.pinnedCRDs fields being referencable basically everywhere in the templates.

With HULL you can do this too and there is a clearly defined place in the HULL concept for such properties that need to be referenced multiple distinct times for object creation or transformation in the hull.objects section: the hull.config.specific dictionary. This hull.config.specific section is specifically intended for this purpose of adding central configuration data that is either singled out for convenient documentation, highlighting and configuration or being used in multiple places within the chart. You can think of this section resembling one of the functions of the values.yaml itself within the classic Helm chart approach, namely to centralize access to configuration values. Technically the hull.config section is processed before the hull.objects section and hence properties defined here and their values (even if derived by a HULL transformation!) are always available for referencing to when defining the objects in the hull.objects section.

To cover the dynamic nature of the JSON transformation you can utilize the hull.util.transformation.tpl transformation.

Enter the `_HT!` transformation

There are some convenience transformations like the hull.util.transformation.bool transformation within HULL but by far the most powerful and flexible is the HULL hull.util.transformation.tpl or _HT! transformation. It executes the Helm tpl function on a given string providing full range of Go templating capabilities as would be the case with Go templating expressions within template files.

Using the hull.util.transformation.tpl transformation you can return different datatypes that are expected for the property's values you apply it on:

string
int
bool
array/list
dictionary/map

An important aspect to keep in mind when producing arrays and dictionaries with the HULL hull.util.transformation.tpl transformation is to use flow style YAML to define the transformation result. This style reduces syntax problems (mostly due to indendation) appearing with the block style YAML that is more typically used when dealing with Helm and Kubernetes. Check the next example on how flow style YAML looks like (it is more similar to JSON and does not rely on correct indentation).

To create the _global and _pinnedCRD sections in the ConfigMap first insert into the existing values.yaml the config.specific block which holds the settings and pinnedCRDs data:

sed '/^hull/r'<(
    echo "  config:"
    echo "    specific:"
    echo "      settings: {}"
    echo "      pinnedCRDs: {}"
  ) -i -- values.yaml

Time to add the tpl transformations to create the JSON content from the now created and referenced sections. The hull.util.transformation.tpl's short form _HT! is being used and in the tpl argument you do a toJson | quote on the source data as in the original source ConfigMap. The result of this operation is returned as the data properties values.

Adding ConfigMap and Secret contents via `inline` specification in `values.yaml`

You likely noticed that within the ConfigMap files data section the actual values for data keys were directly embedded in the values.yaml via the inline property. This is a handy way to be able to specify shorter contents right in place where the ConfigMap is defined.

Add the first JSON transformation via an inline specification:

sed '0,/inline: ""/{s/inline: ""/inline: _HT!{{ toJson (index . "$").Values.hull.config.specific.settings | quote }}/}' -i -- values.yaml

updating your values.yaml to:

metrics-server:
  enabled: false
hull:
  config:
    specific:
      settings: {}
      pinnedCRDs: {}
  objects:
    configmap:
      settings:
        data:
          _global:
            inline: _HT!{{ toJson (index . "$").Values.hull.config.specific.settings | quote }}
          _pinnedCRD:
            inline: ""

Test it out with some YAML content to convert to JSON:

echo 'hull:
  config:
    specific:
      settings:
        settings_one:
          a_string: Some config setting
          a_number: 333
        settings_two:
          a_boolean: true'> ../configs/inline-transformation.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/inline-transformation.yaml .

and check out the JSON content in the ConfigMap:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: '{"settings_one":{"a_number":333,"a_string":"Some config setting"},"settings_two":{"a_boolean":true}}'
  _pinnedCRD: ""
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings

Adding ConfigMap and Secret contents via `path` specification from external files

Alternatively to the inline method you can specify the path to an external file to import content from via usage of the path property and omitting the inline property. It is really simple, just provide a relative path to a file and it will be rendered as a ConfigMap (or Secret) data: entry. This is useful if you have larger contents like from configuration files which you don't want to clutter your values.yaml with. Dynamically computed content of ConfigMap or Secret entries due to usage of template expressions is well suited for supplying it from external files. Especially if you'd have large configuration file like content with many templating expressions it is cleaner to provide the file as external content to not clutter the values.yaml unnecessarily.

Using an external file here for the _pinnedCRD key allows to directly highlight the difference to the inline handling of the settings key via HULL because functionally the same is happening. As a Bonus you can compare the HULL transformation syntax to the regular templating expression syntax as you can use it within an externally imported file, the HULL transformations do not apply to externally imported files but only within the values.yaml tree!

Now you can import the second JSON transformation content via specifying it in an external file to highlight this feature. First add the external file like this:

mkdir files

and echo same templating instruction as above into the file:

echo '{{ toJson .Values.hull.config.specific.pinnedCRDs }}' > files/pinnedCRDs

Lastly add the external file as a source replacing the former inline directive:

sed '0,/inline: ""/{s/inline: ""/path: files\/pinnedCRDs/}' -i -- values.yaml

Then see if this way of handling data works too:

echo 'hull:
  config:
    specific:
      pinnedCRDs:
        another:
          dicionary: test' > ../configs/path-transformation.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/path-transformation.yaml .

you can again see it does actually produces the JSON content:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: '{}'
  _pinnedCRD: '{"another":{"dicionary":"test"}}'
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings

That's it. You have learned how you can start to leverage the power of transformations - particularly the hull.util.transformation.tpl transformation - to improve chart creation and configuration! Done with the ConfigMap and onto the Secret!

Specifying Secrets with HULL

Conveniently creating secrets with HULL is exactly the same process as creating ConfigMaps, all required Base64 encoding is done automatically under the hood even when using the inline functionality.

Do take a look at the existing Secret file in the kubernetes-dashboard chart by typing:

cat ../kubernetes-dashboard/templates/secret.yaml

which gives:

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# kubernetes-dashboard-certs
apiVersion: v1
kind: Secret
metadata:
  labels:
    {{- include "kubernetes-dashboard.labels" . | nindent 4 }}
    {{- if .Values.commonLabels }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonLabels "context" $ ) | nindent 4 }}
    {{- end }}
  annotations:
    {{- if .Values.commonAnnotations }}
    {{- include "common.tplvalues.render" ( dict "value" .Values.commonAnnotations "context" $ ) | nindent 4 }}
    {{- end }}
  name: {{ template "kubernetes-dashboard.fullname" . }}-certs
type: Opaque
---
# kubernetes-dashboard-csrf
apiVersion: v1
kind: Secret
metadata:
  labels:
{{ include "kubernetes-dashboard.labels" . | nindent 4 }}
  name: kubernetes-dashboard-csrf
type: Opaque
---
# kubernetes-dashboard-key-holder
apiVersion: v1
kind: Secret
metadata:
  labels:
{{ include "kubernetes-dashboard.labels" . | nindent 4 }}
  name: kubernetes-dashboard-key-holder
type: Opaque

Interestingly and uncommonly you'll find three secrets without any data entries pre-specified or even the possibility to specify them in the chart. You'll also notice that the csrf and key-holder secrets have static names set while the name of the certs secret is dynamically calulated:

...
name: {{ template "kubernetes-dashboard.fullname" . }}-certs
...
name: kubernetes-dashboard-csrf
...
name: kubernetes-dashboard-key-holder
...

This is likely because the Kubernetes Dashboard application is bound tightly to the Kubernetes world and the application itself accesses the secrets by their static names internally as indicated here. In order to be able to address them by their static names you need to keep their names static too. The default naming behavior for objects in HULL is to create a dynamic name for objects. But you can always opt to create objects with a fixed/static name instead. You only need to add the staticName: true property to the object definition and the object name matches exactly the key name.

Check this out by adding the Secrets with empty content now to our values.yaml configuration with:

echo '    secret:
      certs:
        data: {}
      kubernetes-dashboard-csrf:
        data: {}
        staticName: true
      kubernetes-dashboard-key-holder:
        data: {}
        staticName: true' >> values.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml .

and the Secrets have been created with the differing naming schemes:

---
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: certs
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-certs
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-csrf
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: kubernetes-dashboard-csrf
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-key-holder
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: kubernetes-dashboard-key-holder
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: '{}'
  _pinnedCRD: '{}'
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-settings

In the same vein it is a good time to discuss a transformation that allows to create dynamic names from a static string in other places of charts where objects are being refered to by name and not where they themselves are being named.

Utilizing the `hull.util.transformation.makefullname`/`_HT^` transformation to produce chart specific dynamic names

As touched upon, a common scenario when writing Helm charts is to produce dynamic names for all the Helm charts objects. Regularly the dynamic name consists of a static object name part and a dynamic prefix where the chart and/or release name is prefixed, e.g. assume the static instance name is settings, the chart name my-application and the release name my-release and you may get my-application-my-release-settings as a name for a ConfigMap maybe.

The reasoning behind these dynamic names is that they are supposed to be unique: even when you deploy one chart twice in the same namespace you would have to give the releases individual names, otherwise Helm would fail since it does not allow two releases with the same name in a single namespace. Even though it would be easy to produce counter examples this suffices in the practical world to have no naming clashes of objects managed via Helm charts.

Another configuration option commonly offered in Helm charts is to allow the user to specify a so-called fullnameOverride which then replaces the my-application-my-release prefix with a static prefix of your choosing. While this raises the chance of object instance name collisions obviously it can help with object names becoming unnecessarily long (there is a length cap of at most 63 chars for object names in Kubernetes).

By default all objects that HULL creates and manages have a unique dynamic name and there clearly defined places in Kubernetes object specifications where you address another object of a known and fixed type and there it suffices to supply just the object key name and HULL automatically converts it to the full dynamic name on rendering.

The places where dynamic names are created from key names automatically are:

horizontalpodautoscaler:
- the scaleTargetRef.name
ingress:
- the tls.secretName
- the backend.service.name
container:
- the env.valueFrom.configMapKeyRef
- the env.valueFrom.secretKeyRef
- the envFrom.configMapRef
- the envFrom.secretRef
volume:
- the configMap.name
- the secret.secretName
- the persistentVolumeClaim.claimName

In all these places you can simply use the key of the instance you address and HULL will by default create a dynamic name. However, if it is not a dynamic name you want to reference to you can always add staticName: true next to the property holding the instance name and the value will not be modified on rendering. Examples of this in use will follow.

However in some other situations you may also need to reference a Kubernetes object (created within the same chart) by its name and it is not as clear in advance that the value is a reference to a Kubernetes object by name. Think the configuration of RoleBindings, here is the Kubernetes documentation example of this:

apiVersion: rbac.authorization.k8s.io/v1
# This role binding allows "jane" to read pods in the "default" namespace.
# You need to already have a Role named "pod-reader" in that namespace.
kind: RoleBinding
metadata:
  name: read-pods
  namespace: default
subjects:
# You can specify more than one "subject"
- kind: User
  name: jane # "name" is case sensitive
  apiGroup: rbac.authorization.k8s.io
roleRef:
  # "roleRef" specifies the binding to a Role / ClusterRole
  kind: Role #this must be Role or ClusterRole
  name: pod-reader # this must match the name of the Role or ClusterRole you wish to bind to
  apiGroup: rbac.authorization.k8s.io

If pod-reader would be created within the Helm chart the RoleBinding is defined in you need the capability to enforce a dynamic name in the roleRef. This is where the _HT^ transformation steps in to help you out by providing the same dynamic naming mechanism explained above. You only need to feed it the key name and it will produce a dynamic fullname based on the key name and the charts configuration. If you want to use the fullnameOverride functionality you can also specify the fullnameOverride under the hull.config.general.fullnameOverride configuration property and it will be respected in the creation of all dynamic names. This will be put to good use in the tutorial part on RBAC configuration (where there is a lot of referencing of object instances by name) so the example can be skipped here and left for later.

Besides the _HT!, _HT? and _HT^ transformations there is one more helpful transformation that concludes the out-of-the-box transformations that HULL provides: the hull.util.transformation.get/_HT* get transformation.

Getting values with the `hull.util.transformation.get`/`_HT*` transformation

Similar to the _HT? transformation you can utilize the _HT* transformation to directly get a value via the dot notation path to the source of the reference. When using _HT* you can specify the path to the value to get relative to the .Values dictionary that means you explicitly don't specify any .Values or (index . "$").Values prefix. This works for referenced values of string, integer and boolean types and even for arrays or dictionaries.

Remember the metadata setting usecase where you may want to apply a given set of labels to all objects of a particular 'group'? With _HT* this now becomes possible as in the next example.

By now you have defined a settings ConfigMap and the three Secrets certs, kubernetes-dashboard-csrf and kubernetes-dashboard-key-holder. Say the settings ConfigMap and the certs Secret should be grouped by a common set of labels indicating they are relevant for cluster-level configuration. Additionally the kubernetes-dashboard-csrf and kubernetes-dashboard-key-holder Secrets are to be marked as relevant on application-level. This is not required for the chart conversion but may serve as a fictional grouping example.

Now in this demo sketch the shared labels under hull.config.specific:

echo 'hull:
  config:
    specific:
      labels:
        configuration:
          cluster:
            configuration: "true"
            relevancy: cluster-level
          application:
            configuration: "true"
            relevancy: application-level
  objects:
    configmap:
      settings:
        labels: _HT*hull.config.specific.labels.configuration.cluster
    secret:
      certs:
        labels: _HT*hull.config.specific.labels.configuration.cluster
      kubernetes-dashboard-csrf:
        labels: _HT*hull.config.specific.labels.configuration.application
      kubernetes-dashboard-key-holder:
        labels: _HT*hull.config.specific.labels.configuration.application'> ../configs/get-transformation.yaml \
&& helm template -f ../configs/disable-default-rbac.yaml -f ../configs/get-transformation.yaml .

we have successfully grouped objects by a shared set of labels:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: certs
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    configuration: true
    helm.sh/chart: kubernetes-dashboard-5.2.0
    relevancy: cluster-level
  name: release-name-kubernetes-dashboard-certs
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-csrf
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    configuration: true
    helm.sh/chart: kubernetes-dashboard-5.2.0
    relevancy: application-level
  name: kubernetes-dashboard-csrf
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: Secret
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: kubernetes-dashboard-key-holder
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    configuration: true
    helm.sh/chart: kubernetes-dashboard-5.2.0
    relevancy: application-level
  name: kubernetes-dashboard-key-holder
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
data:
  _global: '{}'
  _pinnedCRD: '{}'
kind: ConfigMap
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: settings
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    configuration: true
    helm.sh/chart: kubernetes-dashboard-5.2.0
    relevancy: cluster-level
  name: release-name-kubernetes-dashboard-settings

Wrap up

This concludes the subject of handling ConfigMaps and Secrets within HULL. Along the way you have learned about HULL transformations which put powerful templating into the values.yaml processing. At this point feel free to play around with the already created example files in the config folder and check if you get the expected output rendered. Of course you can also create new ones for testing the functionality!

Your values.yaml should at this stage look like this:

cat values.yaml

metrics-server:
  enabled: false
hull:
  config:
    specific:
      settings: {}
      pinnedCRDs: {}
  objects:
    configmap:
      settings:
        data:
          _global:
            inline: _HT!{{ toJson (index . "$").Values.hull.config.specific.settings | quote }}
          _pinnedCRD:
            path: files/pinnedCRDs
    secret:
      certs:
        data: {}
      kubernetes-dashboard-csrf:
        data: {}
        staticName: true
      kubernetes-dashboard-key-holder:
        data: {}
        staticName: true

Pretty compact. The 80 lines of configuration in the original kubernetes-dashboard chart that were spent to define the ConfigMap and the Secrets were reduced to 20 and that is even excluding the relevant lines from the original values.yaml. That means a reduction of more than half of the lines of code that require maintenance. Yet at the same time you are gaining the full possibility to overwrite any objects property. When working on the workload objects (Deployments, DaemonSet and Jobs) this reduction of the code to be maintained is even more visible and you will see that you need roughly half the code lines then to achieve even more than what is possible with the original chart.

Now is the right time to store your current values.yaml as values.tutorial-part.yaml in the charts folder:

cp values.yaml values.tutorial-part.yaml

This file is supposed to hold the individual outcome of each tutorial part from now on, concentrating on the aspects that are in focus of the respective tutorial part.

Additionally a values.full.yaml will from now on be maintained and will be built upon in each tutorial part and become the final complete values.yaml for the chart. Basically it represents the outcome of the whole tutorial series. Within this constantly growing file all intermediate tutorial results are being added. For this first tutorial where first objects were created it is the same as the values.intermediate.yaml obviously but starting from the next tutorial part it will grow further. So at this time just copy the values.yaml too:

cp values.yaml values.full.yaml

By backing up your progress this way the 'working' values.yaml can be reset or modified for each tutorial part to limit the output to look at (since we do not require all objects that were created so far each time) but only those in focus of a tutorial part.

Otherwise that is the end of this tutorial part, the outcome of it is found here. The next tutorial looks at configuration of ServiceAccounts and RBAC matters.

Thanks for reading and hopefully you found it useful and/or interesting!

HULL Tutorial 02: Setting up a Helm Chart based on HULL

gre9ory — Tue, 31 May 2022 11:24:11 +0000

Introduction

This article series will go step by step through building a Helm Chart based on the HULL library. To allow a good comparison with the traditional Helm chart creation process and for educational purposes the goal is to rewrite the kubernetes-dashboard Helm chart in it's latest version that exists at time of writing (which is version 5.2.0).

You may ask why the kubernetes-dashboard Helm chart? For a number of reasons this is an interesing topic for this tutorial:

the kubernetes-dashboard Helm chart is most likely one of the most frequently downloaded and used Helm chart around the globe. Many people interact with it daily and may have a deeper understanding of its structure
it has a medium complexity which makes the goal of translating it to a HULL based chart on the one hand has the power of showcasing the real-life applicability of the HULL library to Helm chart creation and on the other hand is doable with a reasonable amount of effort
lastly, a deep dive into such a commonly used Helm Chart may still offer interesting insights to you if you are new-ish to understanding Helm chart mechanics or want to get to learn the kubernetes-dashboard's particular charts architecture better

Getting Helm

Before you can get started you need to make sure you have a fresh Helm version installed. Then open up a Linux terminal of your choice and when you type in:

helm version

the output should be similar to this:

version.BuildInfo{Version:"v3.6.3", GitCommit:"d506314abfb5d21419df8c7e7e68012379db2354", GitTreeState:"clean", GoVersion:"go1.16.5"}

Now you are good to go!

Creating the test project

First switch to your working directory, eg. home:

cd ~

and there create a directory for our project and first tutorial part and switch to it:

mkdir kubernetes-dashboard-hull && mkdir kubernetes-dashboard-hull/02_setup && cd kubernetes-dashboard-hull/02_setup

Getting the original `kubernetes-dashboard` chart

For reference and analysis you can download a copy of the original kubernetes-dashboard helm chart and extract it like this:

curl -L https://kubernetes.github.io/dashboard/kubernetes-dashboard-5.2.0.tgz -o kubernetes-dashboard.tgz && tar -xvzf kubernetes-dashboard.tgz -C . && rm kubernetes-dashboard.tgz

To check if it was succesful list the kubernetes-dashboard folder:

ls -R kubernetes-dashboard

and you should see all the extracted files:

kubernetes-dashboard:
Chart.lock  Chart.yaml  README.md  charts  templates  values.yaml

kubernetes-dashboard/charts:
metrics-server

kubernetes-dashboard/charts/metrics-server:
Chart.yaml  README.md  ci  templates  values.yaml

kubernetes-dashboard/charts/metrics-server/ci:
ci-values.yaml

kubernetes-dashboard/charts/metrics-server/templates:
NOTES.txt     apiservice.yaml                     clusterrole.yaml                        clusterrolebinding.yaml  pdb.yaml  rolebinding.yaml  serviceaccount.yaml
_helpers.tpl  clusterrole-aggregated-reader.yaml  clusterrolebinding-auth-delegator.yaml  deployment.yaml          psp.yaml  service.yaml

kubernetes-dashboard/templates:
NOTES.txt       clusterrole-metrics.yaml         clusterrolebinding-readonly.yaml  ingress.yaml        psp.yaml          secret.yaml          servicemonitor.yaml
_helpers.tpl    clusterrole-readonly.yaml        configmap.yaml                    networkpolicy.yaml  role.yaml         service.yaml
_tplvalues.tpl  clusterrolebinding-metrics.yaml  deployment.yaml                   pdb.yaml            rolebinding.yaml  serviceaccount.yaml

Setting up a HULL Chart

Good, now proceed by creating a new empty HULL based Helm chart. The steps are documented here but you will create it from scratch here to understand what is needed.

One way to get started is by using the helm create command to create the folder structure for an empty Helm chart. Run this command to create our kubernetes-dashboard-hull Helm chart:

helm create kubernetes-dashboard-hull

should produce this answer:

Creating kubernetes-dashboard-hull

That should have created a folder kubernetes-dashboard-hull with the usual required and example Helm chart files in there. Switch to the folder and examine the contents:

cd kubernetes-dashboard-hull && ls -R

to find the default files for a new scaffolded Helm chart:

.:
Chart.yaml  charts  templates  values.yaml

./charts:

./templates:
NOTES.txt  _helpers.tpl  deployment.yaml  hpa.yaml  ingress.yaml  service.yaml  serviceaccount.yaml  tests

./templates/tests:
test-connection.yaml

Delete examples and tests in the /templates folder, nothing besides the hull.yaml is needed:

rm -rf templates/* && ls -R

shows this:

.:
Chart.yaml  charts  templates  values.yaml

./charts:

./templates:

Additionally empty the values.yaml with the example data:

echo '' > values.yaml

Now edit the mandatory Chart.yaml which is updated to reflect the original charts information. Furthermore add the HULL library as requirement which is necessary to be able to use HULL.

Choosing a HULL version

When choosing a HULL version for this, it is recommended that HULLs major.minor version must at least match the kubeVersion field otherwise the API version of objects created by HULL may be yet unknown to the clusters API version. Each HULL release branch is aligned with a specific Kubernetes version such as 1.21, 1.22, 1.23 and so on. The objects that HULL renders out will always be of the latest API version of the given object type that matches the HULL librarys version. So when an API is upgraded from beta to stable in a Kubernetes version jump, the latter HULL version will create objects with the stable API version and the former will create the beta API versioned objects. It is recommended to leave the kubeVersion set at 1.21.0 for this example so you will be able to work against any Kubernetes cluster with a version of 1.21.0 or above.

Replace 1.23.3 below with the latest available HULL version and match the kubeVersion accordingly:

echo 'apiVersion: v2
appVersion: 2.5.0
dependencies:
- condition: metrics-server.enabled
  name: metrics-server
  repository: https://kubernetes-sigs.github.io/metrics-server/
  version: 3.5.0
- name: hull
  version: "1.23.3"
  repository: "https://vidispine.github.io/hull"
description: General-purpose web UI for Kubernetes clusters
home: https://github.com/kubernetes/dashboard
icon: https://raw.githubusercontent.com/kubernetes/kubernetes/master/logo/logo.svg
keywords:
- kubernetes
- dashboard
kubeVersion: ">=1.21.0-0"
maintainers:
- email: cdesaintmartin@wiremind.fr
  name: desaintmartin
name: kubernetes-dashboard
sources:
- https://github.com/kubernetes/dashboard
version: 5.2.0' > Chart.yaml

Before starting work on the values.yaml you should download the HULL library by the Helm way of updating Chart dependencies:

helm dependency update

to download the HULL chart from the GitHub hosted HelmChart repository and the other subchart metrics-server which you can optionally co-deploy:

Getting updates for unmanaged Helm repositories...
...Successfully got an update from the "https://kubernetes-sigs.github.io/metrics-server/" chart repository
...Successfully got an update from the "https://vidispine.github.io/hull" chart repository
Saving 2 charts
Downloading metrics-server from repo https://kubernetes-sigs.github.io/metrics-server/
Downloading hull from repo https://vidispine.github.io/hull
Deleting outdated charts

Great, one tiny thing left before you can start defining the objects of our kubernetes-dashboard-hull Chart: copy over the hull.yaml from the now locally downloaded subchart to the main charts template folder. Without this step, nothing can be rendered via HULL since the hull.yaml contains the logic to convert values.yaml object definitions to rendered YAML files. We can do this with a one-liner where we extract the packaged HULL tgz file from the /charts directory to a local temp directory, copy over the hull.yaml and clean up the temp directory afterwards:

mkdir _tmp && tar -xvzf charts/hull-1.23.3.tgz -C _tmp && cp _tmp/hull/hull.yaml templates/hull.yaml && rm -rf _tmp

prints out the temporarily extracted files:

hull/Chart.yaml
hull/Chart.lock
hull/values.yaml
hull/values.schema.json
hull/templates/_metadata.tpl
hull/templates/_metadata_annotations.tpl
hull/templates/_metadata_chartref.tpl
hull/templates/_metadata_fullname.tpl
hull/templates/_metadata_header.tpl
hull/templates/_metadata_labels.tpl
hull/templates/_metadata_name.tpl
hull/templates/_objects.tpl
hull/templates/_objects_base_plain.tpl
hull/templates/_objects_base_pod.tpl
hull/templates/_objects_base_rbac.tpl
hull/templates/_objects_base_role.tpl
hull/templates/_objects_base_spec.tpl
hull/templates/_objects_base_webhook.tpl
hull/templates/_objects_configmap.tpl
hull/templates/_objects_cronjob.tpl
hull/templates/_objects_horizontalpodautoscaler.tpl
hull/templates/_objects_ingress.tpl
hull/templates/_objects_pod.tpl
hull/templates/_objects_pod_container.tpl
hull/templates/_objects_pod_volume.tpl
hull/templates/_objects_registry.tpl
hull/templates/_objects_secret.tpl
hull/templates/_objects_service.tpl
hull/templates/_util.tpl
hull/templates/_util_transformations.tpl
hull/.helmignore
hull/CHANGELOG.md
hull/LICENSE
hull/README.md
hull/doc/architecture.md
hull/doc/development.md
hull/doc/json_schema_validation.md
hull/doc/objects_base.md
hull/doc/objects_configmaps_secrets.md
hull/doc/objects_customresource.md
hull/doc/objects_horizontalpodautoscaler.md
hull/doc/objects_ingress.md
hull/doc/objects_pod.md
hull/doc/objects_registry.md
hull/doc/objects_role.md
hull/doc/objects_service.md
hull/doc/objects_webhook.md
hull/doc/setup.md
hull/doc/transformations.md
hull/files/examples/authservice_values.yaml
hull/files/examples/medialogger_values.yaml
hull/files/scripts/HullChart.ps1
hull/files/scripts/SetChartVersion.ps1
hull/files/scripts/SetYamlValues.ps1
hull/files/templates/hull-clusterrole.yaml
hull/files/templates/hull-clusterrolebinding.yaml
hull/files/templates/hull-configmap.yaml
hull/files/templates/hull-cronjob.yaml
hull/files/templates/hull-customresource.yaml
hull/files/templates/hull-daemonset.yaml
hull/files/templates/hull-deployment.yaml
hull/files/templates/hull-endpoints.yaml
hull/files/templates/hull-horizontalpodautoscaler.yaml
hull/files/templates/hull-ingress.yaml
hull/files/templates/hull-ingressclass.yaml
hull/files/templates/hull-job.yaml
hull/files/templates/hull-mutatingwebhookconfiguration.yaml
hull/files/templates/hull-networkpolicy.yaml
hull/files/templates/hull-persistentvolume.yaml
hull/files/templates/hull-persistentvolumeclaim.yaml
hull/files/templates/hull-poddisruptionbudget.yaml
hull/files/templates/hull-podsecuritypolicy.yaml
hull/files/templates/hull-priorityclass.yaml
hull/files/templates/hull-registry.yaml
hull/files/templates/hull-resourcequota.yaml
hull/files/templates/hull-role.yaml
hull/files/templates/hull-rolebinding.yaml
hull/files/templates/hull-secret.yaml
hull/files/templates/hull-service.yaml
hull/files/templates/hull-serviceaccount.yaml
hull/files/templates/hull-servicemonitor.yaml
hull/files/templates/hull-statefulset.yaml
hull/files/templates/hull-storageclass.yaml
hull/files/templates/hull-validatingwebhookconfiguration.yaml
hull/hull.yaml

Now check if the hull.yaml was copied correctly to the templates folder:

cat templates/hull.yaml

should return:

{{- include "hull.objects.prepare.all" (dict "HULL_ROOT_KEY" "hull" "ROOT_CONTEXT" $) }}

Inspecting default RBAC settings

Fantastic, all in place! If everything went right up to here you can take a first look at what HULL does by default in an otherwise unconfigured Helm chart. For this you can have Helm render out the YAMLs to stdout where you can study them instead of directly deploying objects to a cluster. helm template is the command used for this rendering. If you have an error complaining about version incompatibility you have to update your Helm installation so that helm template runs against a new API version.

Go on by templating out what we have in our "empty" chart so far:

helm template .

giving us an unexpected amount of objects:

---
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: release-name-metrics-server
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/clusterrole-aggregated-reader.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: system:metrics-server-aggregated-reader
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
  - apiGroups:
      - metrics.k8s.io
    resources:
      - pods
      - nodes
    verbs:
      - get
      - list
      - watch
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/clusterrole.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: system:release-name-metrics-server
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
rules:
  - apiGroups:
    - ""
    resources:
      - pods
      - nodes
      - nodes/stats
      - namespaces
      - configmaps
    verbs:
      - get
      - list
      - watch
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/clusterrolebinding-auth-delegator.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: release-name-metrics-server:system:auth-delegator
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:auth-delegator
subjects:
  - kind: ServiceAccount
    name: release-name-metrics-server
    namespace: default
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/clusterrolebinding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: system:release-name-metrics-server
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: system:release-name-metrics-server
subjects:
  - kind: ServiceAccount
    name: release-name-metrics-server
    namespace: default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/rolebinding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: release-name-metrics-server-auth-reader
  namespace: kube-system
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: extension-apiserver-authentication-reader
subjects:
  - kind: ServiceAccount
    name: release-name-metrics-server
    namespace: default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: release-name-metrics-server
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
spec:
  type: ClusterIP
  ports:
    - name: https
      port: 443
      protocol: TCP
      targetPort: https
  selector:
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: release-name-metrics-server
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: metrics-server
      app.kubernetes.io/instance: release-name
  template:
    metadata:
      labels:
        app.kubernetes.io/name: metrics-server
        app.kubernetes.io/instance: release-name
    spec:
      serviceAccountName: release-name-metrics-server
      priorityClassName: "system-cluster-critical"
      containers:
        - name: metrics-server
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            runAsUser: 1000
          image: k8s.gcr.io/metrics-server/metrics-server:v0.5.0
          imagePullPolicy: IfNotPresent
          args:
            - --cert-dir=/tmp
            - --secure-port=4443
            - --kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname
            - --kubelet-use-node-status-port
            - --metric-resolution=15s
          ports:
          - name: https
            protocol: TCP
            containerPort: 4443
          livenessProbe:
            failureThreshold: 3
            httpGet:
              path: /livez
              port: https
              scheme: HTTPS
            initialDelaySeconds: 0
            periodSeconds: 10
          readinessProbe:
            failureThreshold: 3
            httpGet:
              path: /readyz
              port: https
              scheme: HTTPS
            initialDelaySeconds: 20
            periodSeconds: 10
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
---
# Source: kubernetes-dashboard/charts/metrics-server/templates/apiservice.yaml
apiVersion: apiregistration.k8s.io/v1
kind: APIService
metadata:
  name: v1beta1.metrics.k8s.io
  labels:
    helm.sh/chart: metrics-server-3.5.0
    app.kubernetes.io/name: metrics-server
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/version: "0.5.0"
    app.kubernetes.io/managed-by: Helm
spec:
  group: metrics.k8s.io
  groupPriorityMinimum: 100
  insecureSkipTLSVerify: true
  service:
    name: release-name-metrics-server
    namespace: default
  version: v1beta1
  versionPriority: 100

Hmm, quite a lot of objects. This is because the templating command rendered both the HULL default RBAC objects as well as the metrics-server subchart default objects. Since we did not explicitly enable the deployment of the metrics-server subchart this may be considered a Helm bug, however let us just disable the metrics-server chart deployment for this tutorial by typing:

echo 'metrics-server:
  enabled: false' > values.yaml

Editing the values.yaml has the direct effect on the output that metrics-server subchart deployment is disabled. Now the helm template . output should only contain the HULL objects which are created by default.

You can verify this by entering again:

helm template .

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
rules: []
---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: release-name-kubernetes-dashboard-default
subjects:
- kind: ServiceAccount
  name: release-name-kubernetes-dashboard-default

There is already a lot you can gather from this output. One thing you may ask is: why are there already objects created while I haven't even defined anything yet? That's because by default, HULL will render a 'default' set of RBAC objects which you can use and fine-tune for your application. The objects that are automatically created are:

a default ServiceAccount with name <release-name>-<chart-name>-default which is preconfigured for all pods as the serviceAccountName to use
a default Role with name <release-name>-<chart-name>-default which initially has no rules but you can easily add them as needed
a default RoleBinding with name <release-name>-<chart-name>-default that connects the <release-name>-<chart-name>-default Role with the <release-name>-<chart-name>-default ServiceAccount

This is like RBAC bootstraping which you can build upon easily - but you may have different needs so if this setup does not fit your usecase, you can disable this default set of RBAC objects and specify different RBAC objects more tailored to your needs. The investigation of options for RBAC configuration are the subject of an upcoming tutorial in this series.

However, while using RBAC is the default with HULL you can also optionally turn off the rendering of RBAC objects all together if that is what you want (of course not recommended :) ). HULL offers the following chart global switch to opt out of RBAC and if false RBAC related objects will not be rendered anymore:

hull:
  config:
    general:
      rbac: false

Inspecting the autogenerated metadata

Another standout aspect here is the autogenerated metadata for all objects which adheres to the best practice Kubernetes metadata definition and Helm's recommendation on the subject matter. Using HULL you get this default metadata created without you having to do anything and on top of this it is easy to enrich all objects or objects of a particular type or just individual objects with metadata even further which is also covered in the remainder of this tutorial.

For example, check out the metadata block of the ServiceAccount that was rendered:

---
# Source: kubernetes-dashboard/templates/hull.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations: {}
  labels:
    app.kubernetes.io/component: default
    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: kubernetes-dashboard
    app.kubernetes.io/part-of: undefined
    app.kubernetes.io/version: 2.5.0
    helm.sh/chart: kubernetes-dashboard-5.2.0
  name: release-name-kubernetes-dashboard-default

Autogenerating standard metadata and being able to define inheritable metadata is a convenience feature that enforces uniformity of objects and thus simplifies operations on them.

Wrap up

That's it for Part 2, Part 3 looks at ConfigMaps and Secrets and you will add your first custom objects to the kubernetes-dashboard-hull Helm chart! You can check out the complete code created so far as the outcome of this Part 2 here.

Thanks a lot for reading! Hope to see you in Part 3!

HULL Tutorial 01: Introducing HULL, the Helm Universal Layer Library

gre9ory — Tue, 31 May 2022 11:23:28 +0000

Introduction

The goal of this series of articles is to introduce the features and explain the functionality of the Helm Universal Layer Library - in short HULL. It is a Helm library chart which can help in efficiently creating and managing applications in Kubernetes. The HULL project is open source and you can find it on GitHub:

vidispine / hull

The incredible HULL - Helm Uniform Layer Library - is a Helm library chart to improve Helm chart based workflows

HULL - Helm Uniform Layer Library

This repository contains the HULL Helm library chart. It is designed to ease building, maintaining and configuring Kubernetes objects in Helm charts and can be added to any Helm chart as an addon to enhance functionality without any risk of breaking existing Helm chart configurations.

The chart itself and all documentation related to it can be found in the hull folder which is the root folder of the HULL library helm chart.

The Kubernetes API JSON Schemas are stored in the kubernetes-json-schema folder.

Below is the HULL charts README.md:

Abstractions need to be maintained - Kelsey Hightower

Introduction

One major design aspect of Helm is that it forces the user to create individual abstractions of the Kubernetes configuration of applications. For each individual Helm Chart that is realized in form of YAML templates in a Helm charts /templates folder. These template files, containing…

View on GitHub

If you are unfamiliar with the terms Helm and Kubernetes a brief introduction will follow. However if you have no experience with Kubernetes and Helm it is recommended to study and get practical experience first before proceeding with the tutorials because some familarity with the concepts is required to follow the article(s).

Kubernetes is the defacto standard in modern application deployment and management, especially in the cloud. Helm is a wide-spread tool for packaging and managing Kubernetes applications in form of so-called Helm Charts. Helm supports the concept of 'Library' charts which in itself do not contain deployable objects but only helper funcions to foster Helm chart creation and configuration. HULL falls into this category and can be thought of as an extension or plugin to Helm.

Before getting started with creating a real-life HULL based Helm chart step-by-step in the next articles of this series, some light shall be shed on the concept of HULL and how it affects the Helm Chart based workflow in this introduction. Feel free to skip to the next article in the series if you like to start more practically. Yet it is recommended read on to have an idea why you might want to use HULL (or why not).

Chart design with Helm

Kubernetes objects are typically defined as YAML files and submitting these YAML files to the Kubernetes API (for example via kubectl commands) will create them as entities in the Kubernetes cluster. An application normally will consist of multiple objects such as Deployments, ConfigMaps, Ingresses and so on. Helm expects all the YAML files it needs to deploy to be created in the /templates folder of a Helm chart which is to be deployed.

Building a Helm chart now starts at defining which Kubernetes objects need to be created and which means to adapt them need to be provided in order to be able to run your application under a variety of conditions. Helm charts need to be deployable to different environments such as development, staging or production where different endpoints, credentials, resource sizings etc. all need to be configurable. Or simply think about cloud versus on premise systems where different rules apply in terms of networking, load balancing and scaling. All these aspects need to be tweakable in your applications Helm chart if your application is intended for wide-spread usability.

With plain Helm, technically all objects that may be created under a certain scenario need to be scaffolded in the /templates folder in form of Kubernetes YAML files. To exactly control the logic of which files need to be deployed and which values need to be modified in a particular system, Helm integrates a templating language (Go templating in this case). Using templating expressions in the Kubernetes YAML files it becomes possible to influence the templating logic and produce valid Kubernetes YAML files for a particular scenario (given that the scenario was considered when designing the chart).

The external source for controling the templating logic is in the first step the so-called values.yaml file which is contained in each Helm chart. It serves multiple purposes in reality:

provide reasonable defaults that should satisfy most system needs → defaulting
provide an overview of the configuration options a particular Helm chart aims to implement → documentation purpose

The values.yaml should never be modified itself on deployment for a particular system, it is a static artifact which itself can be modified by overlaying a system-specific configuration file that holds the deviations from the defaults which are required for a particular deployment scenario. Technically the additional system-specific configuration file must match the YAML structure of the values.yaml so its content can be merged with that of the values.yaml. It is even possible to provide multiple system-specific configuration files which will be merged in a defined order. The overlaying configuration files always have precedence over the defaults naturally.

For visualization consider some example mappings of a fictitious Helm chart with one deployment and a configmap in the /templates folder:

The following can be deduced from the example shown above:

the more objects my application requires the more template files need to be created
with each template file a significant amount of boilerplate YAML structure needs to be created
the more aspects of objects that require controlling, the more mappings need to be manually defined
there is no fixed naming relation between source values in values.yaml and the targeted values in the templates.

The Good

Flexibility

The most positive aspects of the above outlined approach is full flexibility in defining what the mappings shall do. Hence it is possible to control aspects of:

multiple objects with a single configuration value (1:n)
single objects with a combination of multiple configuration values (n:1)
multiple objects with combination of multiple configuration values (n:n)

Basically anything is possible but must be explicitly realized by writing the templating logic - even the most simple 1:1 projections. Each Helm chart has in that sense its own individual API which can be tailored towards the usage of the application.

The Bad

Implementation

While the Helm mapping flexibility shines when complex application configurations are required, it cannot on the other hand work without existance of explicit mappings. Considering that within a regular Helm chart typically a significant number of the implemented mappings are rather simple 1:1 mappings between values.yaml properties and single object fields involving no further logic, the Helm mapping approach adds a noticeable overhead to chart writing. For each mapping or projection, template files for the objects need to be created, the templating logic needs to be inserted correctly and the values.yaml needs to be updated to indicate the mappable property and the underlying logic needs to be documented.

Maintenance

As seen there is a significant amount of manual caretaking required when developing and maintaining a Helm chart this way. Consider a real life Helm chart having dozens of objects with hundreds of YAML lines where many mapped values in the templates may need configuring. Furthermore often configurable options on objects are left out initially because they are either not as relevant as others to the chart creator or out of laziness. If someone needs to configure such an option for his deployment scenario the chart needs to be adapted by either submitting a pull request, local forking or any other similar method.

Intransparency

From the perspective of someone who is proficient with Kubernetes it is often unnecessarily unclear how to achieve the desired Kubernetes object configuration without inspection of the mappings between values.yaml and the templates. In this sense, each Helm chart has its own unique API which requires analysis to understand the effects configuration changes in values.yaml have on the templates. The documentation of this interface, the values.yaml comments, often lack in explaining the effects that setting a specific property has on the generated templates. Meanwhile certain conventions have been established that can be found in multiple charts but there is no guarantee that an identical named property in values.yaml will have the same effect in different charts.

What is the difference when using HULL?

The HULL library Helm chart provides a single common interface to specifying Kubernetes objects within Helm Charts. The interface itself is based on the Kubernetes API schema itself which is integrated as a JSON schema in the HULL chart. Since all objects are defined directly in the values.yaml under the hull key there is no need to create and maintain custom template files when creating objects with HULL, everything happens in the values.yaml.

The following diagram sketches how the myapp Helm chart would be built and processed when using HULL:

Being able to directly manipulate any object's property is advantageous in getting rid of the need for implementing explicit mappings, but it would alone not be sufficient to model more complex aspects such as the mentioned 1:n, n:1 or n:n mappings. To cater for this, HULL integrates a unique mechanism called HULL transformations to also allow integrating Go Templating expressions into the values.yaml itself without violating the constraint that the values.yaml file must be valid YAML.

This means you bascially have the same toolset available as with the regular Helm chart workflow but you can restrict yourself to only model configurational relations where it is useful or required. There is no need to model all exposed object properties explicitly, resulting in the amount of code to maintain within a Helm chart to be reduced drastically. Depending on application structure more than 50% of overall lines of configuration code can be saved when building a Helm chart with HULL.

So why would you want to choose using HULL?

The strengths of the HULL based approach are:

having less work when creating or maintaing a larger number of Helm charts since HULL based charts reduce the 'boilerplating' of template files to a minimum. Only explicitly model what you actually want or need to model explicitly saves time and effort in chart creation.
giving the chart users the full flexibility to configure all aspects of any Kubernetes objects right away without having to patch an existing Helm chart.
providing convenience features that simplify common tasks in the context of Helm chart creation. Automatic creation of extensive metadata is done without additional effort and including external files is done within a few lines of configuration.

So whenever you either maintain many not overly complex Helm charts and want to have a fully flexible, maintanable, documented and common interface to all of them, HULL may be the right choice for you.

If on the other hand you manage a single or small number of Helm chart(s) for your company to be deployed to a limited number of environments you might not benefit as much from building charts around HULL though because the benefit pays of when you have to scale the chart creation process.

Wrap Up

Thanks for reading and hoping this sparked your interest. If you'd like to please proceed with the tutorial on chart building with HULL where the popular kubernetes-dashboard Helm chart is being 'reinterpreted' using HULL to showcase its applicability to real life use cases!

DEV Community: gre9ory

HULL Tutorial 08: Wrapping up with a Summary and Analysis

Summary

Lines of Code

HULL Tutorial 07: Configuring Advanced Objects

Preparation

Using in-built ServiceMonitors and CRDs

Specifying NetworkPolicies

Specifying a PodDisruptionBudget

Setting up PodSecurityPolicies

Wrap Up

HULL Tutorial 06: Writing Services and Ingresses

Preparation

Check for existing Service API objects

Defining Services in HULL

A closer look at selectors of Services

Defining Ingresses for inbound traffic

Another Wrap Up

HULL Tutorial 05: Defining Workload objects

Preparation

Examining existing workloads

Specifying workloads with HULL

Automated selector population

Specifying the Pod template

The main container name

The imagePullSecrets and image.registry feature

Dynamically creating args

Seperating out configuration to hull.config.specific

Putting it all together

Wrap Up

HULL Tutorial 04: Configuring ServiceAccounts and RBAC

Preparation

Examining the existing RBAC objects

Choosing ServiceAccounts for pods in HULL

Using the release specific default ServiceAccount

Using the Kubernetes 'default' ServiceAccount

Using a ServiceAccount defined outside of Helm Chart

Using release specific non-default ServiceAccounts

Specifying unique and non-default dynamic ServiceAccounts

Specifying non-default static ServiceAccounts

Defining a RoleBinding

Configuring Roles

Writing ClusterRole and ClusterRoleBindings

ClusterRoles

ClusterRoleBinding

Converting the existing Cluster-scope RBAC objects

Wrap up

HULL Tutorial 03: Integrating ConfigMaps and Secrets

Preparation

Analyzing the existing ConfigMaps

Creating ConfigMaps with HULL

Adding Metdata to objects globally, on object type and object level

Using HULL transformations

The _HT? transformation

Enter the _HT! transformation

Adding ConfigMap and Secret contents via inline specification in values.yaml

Adding ConfigMap and Secret contents via path specification from external files

Specifying Secrets with HULL

Utilizing the hull.util.transformation.makefullname/_HT^ transformation to produce chart specific dynamic names

Getting values with the hull.util.transformation.get/_HT* transformation

Wrap up

HULL Tutorial 02: Setting up a Helm Chart based on HULL

Introduction

Getting Helm

Creating the test project

Getting the original kubernetes-dashboard chart

Setting up a HULL Chart

Choosing a HULL version

Inspecting default RBAC settings

Inspecting the autogenerated metadata

Wrap up

HULL Tutorial 01: Introducing HULL, the Helm Universal Layer Library

Introduction

vidispine / hull

The incredible HULL - Helm Uniform Layer Library - is a Helm library chart to improve Helm chart based workflows

HULL - Helm Uniform Layer Library

Introduction

Chart design with Helm

The Good

Flexibility

A closer look at `selector`s of Services

Automated `selector` population

Specifying the Pod `template`

The main container `name`

The `imagePullSecrets` and `image.registry` feature

Dynamically creating `args`

Seperating out configuration to `hull.config.specific`

The `_HT?` transformation

Enter the `_HT!` transformation

Adding ConfigMap and Secret contents via `inline` specification in `values.yaml`

Adding ConfigMap and Secret contents via `path` specification from external files

Utilizing the `hull.util.transformation.makefullname`/`_HT^` transformation to produce chart specific dynamic names

Getting values with the `hull.util.transformation.get`/`_HT*` transformation

Getting the original `kubernetes-dashboard` chart