public/helm-charts
1
0
Fork 0
mirror of https://github.com/bjw-s-labs/helm-charts.git synced 2025-07-03 16:37:04 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: Add initial docs

Browse source
This commit is contained in:
Bᴇʀɴᴅ Sᴄʜᴏʀɢᴇʀs 2022-08-07 16:32:24 +02:00
parent 155946fb1e
commit 567577762f
No known key found for this signature in database
GPG key ID: BC5E2BD907F9A8EC
15 changed files with 819 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

271
docs/common-library/common-library-add-ons.md Normal file
View file

@ -0,0 +1,271 @@
# Common library add-ons
The common library chart supplies a few add-ons which are meant to simplify some features
you might be looking for. These are sidecars that run in the same pod as your
application you configured it with.
## Code Server
The [code-server](https://github.com/cdr/code-server) add-on can be used to
access and modify persistent volume data in your application. This can be
useful when you need to edit the persistent volume data, for example with
Home Assistant.
### Example values
Below is a snippet from a `values.yaml` using the add-on. More configuration
options can be found in our common chart documentation.
!!! note
This example will mount `/config` into the code-server sidecar.
```yaml
addons:
codeserver:
enabled: true
image:
repository: codercom/code-server
tag: 3.9.0
workingDir: "/config"
args:
- --auth
- "none"
- --user-data-dir
- "/config/.vscode"
- --extensions-dir
- "/config/.vscode"
ingress:
enabled: true
annotations:
kubernetes.io/ingress.class: "nginx"
hosts:
- host: app-config.domain.tld
paths:
- path: /
pathType: Prefix
tls:
- hosts:
- app-config.domain.tld
volumeMounts:
- name: config
mountPath: /config
```
## Wireguard VPN
The Wireguard add-on enables you to force all (or selected) network traffic
through a VPN.
This example shows how to add a Wireguard sidecar to our
[qBittorrent Helm chart](https://github.com/k8s-at-home/charts/tree/master/charts/stable/qbittorrent).
It does not cover all of the configuration possibilities of the
[Wireguard client image](https://github.com/k8s-at-home/container-images/tree/main/apps/wireguard),
but should give a good starting point for configuring a similar setup.
### Example values
Below is an annotated example `values.yaml` that will result in a qBittorrent
container with **all** its traffic routed through a VPN. In order to have
functioning ingress and/or probes, it might be required to open certain
networks or ports on the VPN firewall. That is beyond the scope of this
document. Please refer to the
[Wireguard client image](https://github.com/k8s-at-home/container-images/tree/main/apps/wireguard)
for more details on these environment variables.
!!! note
The `WAIT_FOR_VPN` environment variable is specifically implemented by our
own qBittorrent image, and it will not work with other container images.
```yaml
image:
repository: k8sathome/qbittorrent
tag: v4.3.3
pullPolicy: IfNotPresent
env:
# Our qBittorrent image has a feature that can wait for the VPN to be connected before actually starting the application.
# It does this by checking the contents of a file /shared/vpnstatus to contain the string 'connected'.
WAIT_FOR_VPN: "true"
persistence:
config:
enabled: true
type: emptyDir
mountPath: /config
# This should be enabled so that both the qBittorrent and Wireguard container have access to a shared volume mounted to /shared.
# It will be used to communicate between the two containers.
shared:
enabled: true
type: emptyDir
mountPath: /shared
addons:
vpn:
enabled: true
# This Should be set to `wireguard`. This will set the add-on to use the default settings for Wireguard based connections.
type: wireguard
# If the podSecurityContext is set to run as a different user, make sure to run the Wireguard container as UID/GID 568.
# This is required for it to be able to read certain configuration files.
securityContext:
runAsUser: 568
runAsGroup: 568
env:
# Enable a killswitch that kills all trafic when the VPN is not connected
KILLSWITCH: "true"
# The wireguard configuration file provided by your VPN provider goes here.
#
# Set AllowedIPs to 0.0.0.0/0 to route all traffic through the VPN.
#
# Pay close attention to the PostUp and PreDown lines. They must be added if you wish to run a script when the connection
# is opened / closed.
configFile: |-
[Interface]
PrivateKey = <my-private-key>
Address = <interface address>
DNS = <interface DNS server>
PostUp = /config/up.sh %i
PreDown = /config/down.sh %i
[Peer]
PublicKey = <my-public-key>
AllowedIPs = 0.0.0.0/0
Endpoint = <peer endpoint>
# The scripts that get run when the VPN connection opens/closes are defined here.
# The default scripts will write a string to represent the current connection state to a file.
# Our qBittorrent image has a feature that can wait for this file to contain the word 'connected' before actually starting the application.
scripts:
up: |-
#!/bin/bash
echo "connected" > /shared/vpnstatus
down: |-
#!/bin/bash
echo "disconnected" > /shared/vpnstatus
```
## OpenVPN
Similar to the Wireguard VPN, the OpenVPN add-on enables you to force all
(or selected) network traffic through a VPN.
This example shows how to add an OpenVPN sidecar to our
[qBittorrent Helm chart](https://github.com/k8s-at-home/charts/tree/master/charts/stable/qbittorrent).
It does not cover all of the configuration possibilities of the
[OpenVPN client image](https://github.com/dperson/openvpn-client) by
[@dperson](https://github.com/dperson), but should give a good starting point
for configuring a similar setup.
### Example values
Below is an annotated example `values.yaml` that will result in a qBittorrent
container with **all** its traffic routed through a VPN. In order to have
functioning ingress and/or probes, it might be required to open certain
networks or ports on the VPN firewall. That is beyond the scope of this
document. Please refer to the
[OpenVPN client image](https://github.com/dperson/openvpn-client) for
more details on these environment variables.
!!! note
The `WAIT_FOR_VPN` environment variable is specifically implemented by our
own qBittorrent image, and it will not work with other container images.
```yaml
image:
repository: k8sathome/qbittorrent
tag: v4.3.3
pullPolicy: IfNotPresent
env:
# Our qBittorrent image has a feature that can wait for the VPN to be
# connected before actually starting the application.
# It does this by checking the contents of a file /shared/vpnstatus to
# contain the string 'connected'.
WAIT_FOR_VPN: "true"
persistence:
config:
enabled: true
type: emptyDir
mountPath: /config
# This should be enabled so that both the qBittorrent and OpenVPN container have access to a shared volume mounted to /shared.
# It will be used to communicate between the two containers.
shared:
enabled: true
type: emptyDir
mountPath: /shared
addons:
vpn:
enabled: true
# This Should be set to `openvpn`. This will set the add-on to use the default settings for OpenVPN based connections.
type: openvpn
openvpn:
# This gets read by the Helm chart. The default OpenVPN image reads this and uses it to connect to the VPN provider.
auth: |
myuser
mypassword
# If the podSecurityContext is set to run as a different user, make sure to run the OpenVPN container as root.
# This is required for it to be able to read certain configuration files.
securityContext:
runAsGroup: 0
runAsUser: 0
env:
# Set this environment variable to 'on' to make sure all traffic gets routed through the VPN container.
# Make sure to check the other environment variables for the OpenVPN image to see how you can exclude certain
# traffic from these firewall rules.
FIREWALL: 'on'
# The .ovpn file provided by your VPN provider goes here.
#
# Any CA / certificate must either be placed inline, or provided through an additionalVolumeMount so that OpenVPN can find it.
#
# Pay close attention to the last 3 lines in this file. They must be added if you wish to run a script when the connection
# is opened / closed.
configFile: |-
client
dev tun
proto udp
remote my-awesome-vpn-provider.com 995
remote-cert-tls server
resolv-retry infinite
nobind
tls-version-min 1.2
cipher AES-128-GCM
compress
ncp-disable
tun-mtu-extra 32
auth-user-pass
<ca>
-----BEGIN CERTIFICATE-----
MIIDMTCCAhmgAwIBAgIJAKnGGJK6qLqSMA0GCSqGSIb3DQEBCwUAMBQxEjAQBgNV
-----END CERTIFICATE-----
</ca>
script-security 2
up /vpn/up.sh
down /vpn/down.sh
# The scripts that get run when the VPN connection opens/closes are defined here.
# The default scripts will write a string to represent the current connection state to a file.
# Our qBittorrent image has a feature that can wait for this file to contain the word 'connected' before actually starting the application.
scripts:
up: |-
#!/bin/bash
/etc/openvpn/up.sh
echo "connected" > /shared/vpnstatus
down: |-
#!/bin/bash
/etc/openvpn/down.sh
echo "disconnected" > /shared/vpnstatus
```

283
docs/common-library/common-library-storage.md Normal file
View file

@ -0,0 +1,283 @@
# Common library Storage
This page describes the different ways you can attach storage to charts
using the common library.
## Types
These are the types of storage that are supported in the common library.
Of course, other types are possible with the `custom` type.
### Persistent Volume Claim
This is probably the most common storage type, therefore it is also the
default when no `type` is specified.
It can be attached in two ways.
#### Dynamically provisioned
Charts can be configured to create the required persistentVolumeClaim
manifests on the fly.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `accessMode` | Yes | [link](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) |
| `size` | Yes | [link](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#resources) |
| `mountPath` | No | Where to mount the volume in the main container. Defaults to `/<name_of_the_volume>`. |
| `readOnly` | No | Specify if the volume should be mounted read-only. |
| `nameOverride` | No | Override the name suffix that is used for this volume. |
| `storageClass` | No | Storage class to use for this volume. |
| `retain` | No | Set to true to retain the PVC upon `helm uninstall`. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: pvc
accessMode: ReadWriteOnce
size: 1Gi
```
This will create a 1Gi RWO PVC named `RELEASE-NAME-config` with the default
storageClass, which will mount to `/config`.
#### Existing claim
Charts can be configured to attach to a pre-existing persistentVolumeClaim.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `existingClaim` | Yes | Name of the existing PVC |
| `mountPath` | No | Where to mount the volume in the main container. Defaults to `/<name_of_the_volume>`. |
| `subPath` | No | Specifies a sub-path inside the referenced volume instead of its root. |
| `readOnly` | No | Specify if the volume should be mounted read-only. |
| `nameOverride` | No | Override the name suffix that is used for this volume. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: pvc
existingClaim: myAppData
```
This will mount an existing PVC named `myAppData` to `/config`.
### Empty Dir
Sometimes you need to share some data between containers, or need some
scratch space. That is where an emptyDir can come in.
See the [Kubernetes docs](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir)
for more information.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `medium` | No | Set this to `Memory` to mount a tmpfs (RAM-backed filesystem) instead of the storage medium that backs the node. |
| `sizeLimit` | No | If the `SizeMemoryBackedVolumes` feature gate is enabled, you can specify a size for memory backed volumes. |
| `mountPath` | No | Where to mount the volume in the main container. Defaults to `/<name_of_the_volume>`. |
| `nameOverride` | No | Override the name suffix that is used for this volume. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: emptyDir
```
This will create an ephemeral emptyDir volume and mount it to `/config`.
### Host path
In order to mount a path from the node where the Pod is running you can use a
`hostPath` type persistence item.
This can also be used to mount an attached USB device to a Pod. Note that
this will most likely also require setting an elevated `securityContext`.
See the [Kubernetes docs](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath)
for more information.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `hostPath` | Yes | Which path on the host should be mounted. |
| `hostPathType` | No | Specifying a hostPathType adds a check before trying to mount the path. See Kubernetes documentation for options. |
| `mountPath` | No | Where to mount the volume in the main container. Defaults to the value of `hostPath`. |
| `readOnly` | No | Specify if the volume should be mounted read-only. |
| `nameOverride` | No | Override the name suffix that is used for this volume. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: hostPath
hostPath: /dev
```
This will mount the `/dev` folder from the underlying host to `/dev` in the container.
### configMap
In order to mount a configMap to a mount point within the Pod you can use the
`configMap` type persistence item.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `name` | Yes | Which configMap should be mounted. Supports Helm templating. |
| `defaultMode` | No | The default file access permission bit. |
| `items` | No | Specify item-specific configuration. Will be passed 1:1 to the volumeSpec. |
| `readOnly` | No | Explicitly specify if the volume should be mounted read-only. Even if not specified, the configMap will be read-only. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: configMap
name: mySettings
```
This will mount the contents of the pre-existing `mySettings` configMap to `/config`.
### Secret
In order to mount a Secret to a mount point within the Pod you can use the
`secret` type persistence item.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Yes | |
| `type` | Yes | |
| `name` | Yes | Which Secret should be mounted. Supports Helm templating. |
| `defaultMode` | No | The default file access permission bit. |
| `items` | No | Specify item-specific configuration. Will be passed 1:1 to the volumeSpec. |
| `readOnly` | No | Explicitly specify if the volume should be mounted read-only. Even if not specified, the Secret will be read-only. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: secret
name: mySecret
```
This will mount the contents of the pre-existing `mySecret` Secret to `/config`.
### NFS Volume
To mount an NFS share to your Pod you can either pre-create a persistentVolumeClaim
referring to it, or you can specify an inline NFS volume:
!!! note
Mounting an NFS share this way does not allow for specifying mount options.
If you require these, you must create a PVC to mount the share.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Yes | |
| `type` | Yes | |
| `server` | Yes | Host name or IP address of the NFS server. |
| `path` | Yes | The path on the server to mount. |
| `readOnly` | No | Explicitly specify if the volume should be mounted read-only. Even if not specified, the Secret will be read-only. |
Minimal config:
```yaml
persistence:
config:
enabled: true
type: nfs
server: 10.10.0.8
path: /tank/nas/library
```
This will mount the NFS share `/tank/nas/library` on server `10.10.0.8` to `/config`.
### Custom
When you wish to specify a custom volume, you can use the `custom` type.
This can be used for example to mount configMap or Secret objects.
See the [Kubernetes docs](https://kubernetes.io/docs/concepts/storage/volumes/)
for more information.
| Field | Mandatory | Docs / Description |
| --------------- | --------- | ------------------------------------------------------------------------------------- |
| `enabled` | Yes | |
| `type` | Yes | |
| `volumeSpec` | Yes | Define the raw Volume spec here. |
| `mountPath` | No | Where to mount the volume in the main container. Defaults to the value of `hostPath`. |
| `readOnly` | No | Specify if the volume should be mounted read-only. |
| `nameOverride` | No | Override the name suffix that is used for this volume. |
## Permissions
Charts do not modify file or folder permissions on volumes out of the box.
This means that you will have to make sure that your storage can be written to
by the application.
## Multiple subPaths for 1 volume
It is possible to mount multiple subPaths from the same volume to the main
container. This can be achieved by specifying `subPath` with a list
instead of a string.
!!! note
It is not possible to define `mountPath` at the top level when using this
feature
Examples:
```yaml
persistence:
config:
enabled: true
type: custom
volumeSpec:
configMap:
name: myData
subPath:
- path: myFirstScript.sh
mountPath: /data/myFirstScript.sh
- path: myCertificate.pem
mountPath: /certs/myCertificate.pem
readOnly: true
```
```yaml
persistence:
config:
enabled: true
type: pvc
existingClaim: myAppData
subPath:
- path: .
mountPath: /my_media
- path: Series
mountPath: /series
- path: Downloads
mountPath: /downloads
```

34
docs/common-library/introduction.md Normal file
View file

@ -0,0 +1,34 @@
# Common library
!!! note
The Common library chart is not meant to be installed directly, application
charts use the Common library as a dependency.
## Background
In Helm 3, their team introduced the concept of a
[Library chart](https://helm.sh/docs/topics/library_charts/).
> A library chart is a type of Helm chart that defines chart primitives or
definitions which can be shared by Helm templates in other charts. This
allows users to share snippets of code that can be re-used across charts,
avoiding repetition and keeping charts DRY.
The common library was created because I saw many charts requiring only a
few select configuration options in their Helm charts.
!!! note
Take one of the many applications like `sonarr` or `nzbget`. Each of these
charts only require setting `service`, `port`, `persistence`, `ingress`
and `image` since state and app configuration is handled by the application
itself.
In order to stay somewhat DRY (Don't Repeat Yourself) and keeping with Helm 3
usage for a Library chart, I saw this pattern and decided it was worth it to
create a library. This means each one of these app charts has a
dependency on what we call the `common` library.
## Source code
The source code for the common library chart can be found
[here](https://github.com/bjw-s/helm-charts/tree/main/charts/library/common).