Skip to content

App Template

Background

Since Helm library charts cannot be installed directly I have created a companion chart for the common library.

Usage

This Helm chart can be used to deploy any application. Knowing the specifics of the application you want to deploy like the image, ports, env vars, args, and/or any config volumes will be required. You can also use Kubesearch to search for applications people have deployed with this Helm chart.

In order to use this template chart, you would deploy it as you would any other Helm chart. By setting the desired values, the common library chart will render the desired resources.

Be sure to check out the common library docs and its values.yaml for more information about the available configuration options.

Examples

This is an example values.yaml file that would deploy the vaultwarden application. For more deployment examples, check out the examples folder.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
---
# yaml-language-server: $schema=https://raw.githubusercontent.com/bjw-s/helm-charts/app-template-3.1.0/charts/other/app-template/values.schema.json

controllers:
  main:
    strategy: Recreate

    containers:
      main:
        image:
          # -- image repository
          repository: vaultwarden/server
          # -- image tag
          # this example is not automatically updated, so be sure to use the latest image
          tag: 1.25.2
          # -- image pull policy
          pullPolicy: IfNotPresent

        # -- environment variables.
        # See [image docs](https://github.com/dani-garcia/vaultwarden/blob/main/.env.template) for more details.
        env:
          # -- Config dir
          DATA_FOLDER: "config"

# -- Configures service settings for the chart.
service:
  main:
    controller: main
    ports:
      http:
        port: 80
      websocket:
        enabled: true
        port: 3012

ingress:
  # -- Enable and configure ingress settings for the chart under this key.
  main:
    hosts:
      - host: chart-example.local
        paths:
          - path: /
            pathType: Prefix
            service:
              identifier: main
              port: http
          - path: /notifications/hub/negotiate
            pathType: Prefix
            service:
              identifier: main
              port: http
          - path: /notifications/hub
            pathType: Prefix
            service:
              identifier: main
              port: websocket

route:
  # -- Enable and configure route settings for the chart under this key.
  main:
    parentRefs:
      - name: gateway
        namespace: gateway-namespace
        sectionName: gateway-section
    hostnames:
      - chart-example.local
    rules:
      - matches:
          - path:
              type: PathPrefix
              value: /
        backendRefs:
          - kind: Service
            port: 80
            name: main
            namespace: default
            weight: 1
      - matches:
          - path:
              type: PathPrefix
              value: /notifications/hub/negotiate
        backendRefs:
          - kind: Service
            port: 80
            name: main
            namespace: default
            weight: 1
      - matches:
          - path:
              type: PathPrefix
              value: /notifications/hub
        backendRefs:
          - kind: Service
            port: 3012
            name: main
            namespace: default
            weight: 1

# -- Configure persistence settings for the chart under this key.
persistence:
  config:
    type: persistentVolumeClaim
    accessMode: ReadWriteOnce
    size: 1Gi
    globalMounts:
      - path: /config

Upgrade instructions

From 2.x.x to 3.0.x

The main changes from v2.x to v3.x are the removal of the default main objects and the introduction of JSON schema validation.

Warning

IMPORTANT The introduction of the json schema adds additional validations and restrictions on the contents of your chart values. Things may have been missed during the initial schema creation, so if you run in to any unexpected validation errors please raise an issue

Given the following real-life example values.yaml for app-template v2:

Expand 
---
defaultPodOptions:
  securityContext:
    runAsUser: 568
    runAsGroup: 568
    fsGroup: 568
    fsGroupChangePolicy: "OnRootMismatch"
    supplementalGroups:
      - 65539

controllers:
  main:
    containers:
      main:
        image:
          repository: ghcr.io/onedr0p/sabnzbd
          tag: latest
          pullPolicy: IfNotPresent

service:
  main:
    ports:
      http:
        port: 8080

ingress:
  media:
    enabled: true
    className: "ingress-nginx"
    hosts:
      - host: sabnzbd.bjw-s.dev
        paths:
          - path: /
            service:
              name: main
              port: http

persistence:
  media:
    existingClaim: nas-media
    globalMounts:
      - path: /data/nas-media

The values for app-template v3.x would become this:

---
# yaml-language-server: $schema=https://raw.githubusercontent.com/bjw-s/helm-charts/common-3.1.0/charts/library/common/values.schema.json
defaultPodOptions:
  enableServiceLinks: true
  securityContext:
    runAsUser: 568
    runAsGroup: 568
    fsGroup: 568
    fsGroupChangePolicy: "OnRootMismatch"
    supplementalGroups:
      - 65539

controllers:
  sabnzbd: # this can now be any name you wish
    containers:
      app: # this can now be any name you wish
        image:
          repository: ghcr.io/onedr0p/sabnzbd
          tag: latest
          pullPolicy: IfNotPresent

        probes:
          liveness:
            enabled: true
          readiness:
            enabled: true
          startup:
            enabled: true
            spec:
              failureThreshold: 30
              periodSeconds: 5

service:
  app: # this can now be any name you wish
    controller: sabnzbd
    ports:
      http:
        port: 8080

ingress:
  media: # this can now be any name you wish
    className: "ingress-nginx"
    hosts:
      - host: sabnzbd.bjw-s.dev
        paths:
          - path: /
            service:
              identifier: app
              port: http

persistence:
  media:
    existingClaim: nas-media
    globalMounts:
      - path: /data/nas-media

🚧 Diff view

Expand 
--- old
+++ new
@@ -1,42 +1,55 @@
---
+# yaml-language-server: $schema=https://raw.githubusercontent.com/bjw-s/helm-charts/common-3.1.0/charts/library/common/values.schema.json
 defaultPodOptions:
+  enableServiceLinks: true
   securityContext:
     runAsUser: 568
     runAsGroup: 568
     fsGroup: 568
     fsGroupChangePolicy: "OnRootMismatch"
     supplementalGroups:
       - 65539

 controllers:
-  main:
+  sabnzbd: # this can now be any name you wish
     containers:
-      main:
+      app: # this can now be any name you wish
         image:
           repository: ghcr.io/onedr0p/sabnzbd
           tag: latest
           pullPolicy: IfNotPresent

+        probes:
+          liveness:
+            enabled: true
+          readiness:
+            enabled: true
+          startup:
+            enabled: true
+            spec:
+              failureThreshold: 30
+              periodSeconds: 5
+
 service:
-  main:
+  app: # this can now be any name you wish
+    controller: sabnzbd
     ports:
       http:
         port: 8080

 ingress:
-  media:
-    enabled: true
+  media: # this can now be any name you wish
     className: "ingress-nginx"
     hosts:
       - host: sabnzbd.bjw-s.dev
         paths:
           - path: /
             service:
-              name: main
+              identifier: app
               port: http

 persistence:
   media:
     existingClaim: nas-media
     globalMounts:
       - path: /data/nas-media

Changes in this example

This is not meant as an exhaustive list of changes, but rather a "most common" example.

  • The main object for controllers, containers, services and ingress has been removed from values.yaml and will therefore no longer provide any (both expected and unexpected) default values.
  • The config object for persistence has been removed from values.yaml and will therefore no longer provide any (both expected and unexpected) default values.
  • enableServiceLinks has been disabled by default. In order to explicitly enable serviceLinks, set the value to true.
  • ingress.*.hosts.*.paths.*.service Service references now require either name or identifier to be set.
  • Persistence items of type configMap and secret object references now allow either name or identifier to be set.

From 1.x.x to 2.0.x

Warning

IMPORTANT Because a new label has been introduced in the controller labelSelector (which is an immutable field), Deployments cannot be upgraded in place! More details

Info

Some items (Ingress, ports, persistence items, etc) now default to being enabled by default. However, this is not always the case for some of the items due to overrides in the defaultvalues.yaml`. More background

Given the following real-life example values.yaml for app-template v1:

Expand 
image:
  repository: ghcr.io/onedr0p/sabnzbd
  tag: latest
  pullPolicy: IfNotPresent

podSecurityContext:
  runAsUser: 568
  runAsGroup: 568
  fsGroup: 568
  fsGroupChangePolicy: "OnRootMismatch"
  supplementalGroups:
    - 65539

service:
  main:
    ports:
      http:
        port: 8080

ingress:
  media:
    enabled: true
    ingressClassName: "ingress-nginx"
    hosts:
      - host: sabnzbd.bjw-s.dev
        paths:
          - path: /

persistence:
  media:
    enabled: true
    existingClaim: nas-media
    globalMounts:
      - path: /data/nas-media

probes:
  liveness:
    enabled: false
  readiness:
    enabled: false
  startup:
    enabled: false

The values for app-template v2.x would become this:

defaultPodOptions:
  securityContext:
    runAsUser: 568
    runAsGroup: 568
    fsGroup: 568
    fsGroupChangePolicy: "OnRootMismatch"
    supplementalGroups:
      - 65539

controllers:
  main:
    containers:
      main:
        image:
          repository: ghcr.io/onedr0p/sabnzbd
          tag: latest
          pullPolicy: IfNotPresent

        probes:
          liveness:
            enabled: false
          readiness:
            enabled: false
          startup:
            enabled: false

service:
  main:
    ports:
      http:
        port: 8080

ingress:
  media:
    enabled: true
    className: "ingress-nginx"
    hosts:
      - host: sabnzbd.bjw-s.dev
        paths:
          - path: /
            service:
              name: main
              port: http

persistence:
  media:
    existingClaim: nas-media
    globalMounts:
      - path: /data/nas-media

Changes in this example

This is not meant as an exhaustive list of changes, but rather a "most common" example.

  • podSecurityContext has been moved to defaultPodOptions.securityContext. It is also possible to configure this on a controller-specific basis by moving it to controllers.main.pod.securityContext instead.
  • image has been moved to controllers.main.containers.main.image so that multiple containers can be configured.
  • ingress.media.ingressClassName has been renamed to ingress.main.className.
  • ingress.media.enabled can be removed, since items are considered enabled by default (they can still be disabled by adding enabled: false).
  • ingress.media.hosts.*.paths.*.service is now required since there is no more concept of a default "primary" service.
  • persistence.media.mountPath has been moved to persistence.media.globalMounts.*.path to allow multiple mountPaths for the same persistence item.
  • persistence.media.enabled can be removed, since items are considered enabled by default (they can still be disabled by adding enabled: false).
  • probes has been moved to controllers.main.containers.main.probes so that multiple containers can be configured.

Source code

The source code for the app template chart can be found here.