public/helm-charts
1
0
Fork 0
mirror of https://github.com/bjw-s-labs/helm-charts.git synced 2025-07-01 07: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

83
.ci/mkdocs/mkdocs.yaml Normal file
View file

@ -0,0 +1,83 @@
---
# Project information
site_name: bjw-s | Helm charts | Docs
site_description: Docs for the bjw-s Helm charts repository
site_author: bjw-s
site_url: https://bjw-s.github.io/helm-charts/docs
# Repository
repo_name: bjw-s/helm-charts
repo_url: https://github.com/bjw-s/helm-charts
edit_uri: ""
# Configuration
theme:
name: material
icon:
repo: fontawesome/brands/github-alt
language: en
features:
- navigation.sections
- navigation.tabs
- navigation.tracking
# - navigation.indexes
- search.highlight
- search.share
- search.suggest
palette:
- scheme: default
primary: blue
accent: indigo
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
primary: blue
accent: indigo
toggle:
icon: material/toggle-switch
name: Switch to light mode
font:
text: Roboto
code: Roboto Mono
docs_dir: ../../docs
site_dir: ../../_site
extra_css:
- _static/custom.css
# Plugins
plugins:
- search
- minify:
minify_html: true
# Customization
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/bjw-s
- icon: fontawesome/brands/discord
link: https://discord.gg/sTMX7Vh
# Extensions
markdown_extensions:
- admonition
- abbr
- attr_list
- def_list
- footnotes
- meta
- md_in_html
- toc:
permalink: true
# Page tree
nav:
- Home: index.md
- Common Library:
- Introduction: common-library/introduction.md
- Common Storage: common-library/common-library-storage.md
- Common Add-ons: common-library/common-library-add-ons.md

5
.ci/mkdocs/requirements.txt Normal file
View file

@ -0,0 +1,5 @@
mkdocs==1.3.1
mkdocs-macros-plugin ==0.7.0
mkdocs-material ==8.3.9
mkdocs-minify-plugin==0.5.0
mkdocs-redirects==1.0.5

2
.github/workflows/charts-release-ghpages.yaml vendored
View file

@ -24,7 +24,7 @@ jobs:
name: Release charts
runs-on: ubuntu-22.04
steps:
- name: Get k8s-at-home token
- name: Get GitHub API token
id: get-app-token
uses: getsentry/action-github-app-token@v1
with:

65
.github/workflows/docs-release.yaml vendored Normal file
View file

@ -0,0 +1,65 @@
name: "Docs: Release to GitHub pages"
on:
workflow_dispatch:
push:
branches:
- main
paths:
- '.ci/mkdocs/mkdocs.yaml'
- '.github/workflows/docs-release.yaml'
- "docs/**"
jobs:
release-docs:
name: Release documentation
runs-on: ubuntu-22.04
steps:
- name: Get GitHub API token
id: get-app-token
uses: getsentry/action-github-app-token@v1
with:
app_id: ${{ secrets.BJWS_APP_ID }}
private_key: ${{ secrets.BJWS_APP_PRIVATE_KEY }}
- name: Checkout charts branch
uses: actions/checkout@v3
with:
token: ${{ steps.get-app-token.outputs.token }}
path: "src"
fetch-depth: 0
- name: Checkout gh-pages branch
uses: actions/checkout@v3
with:
token: ${{ steps.get-app-token.outputs.token }}
path: "dest"
ref: "gh-pages"
fetch-depth: 0
- name: Install Python
uses: actions/setup-python@v4
with:
python-version: "3.10"
- name: Install mkdocs
shell: bash
working-directory: src
run: |
pip install -r ./.ci/mkdocs/requirements.txt
- name: Build documentation
shell: bash
working-directory: src
run: |
mkdocs build --config-file ./.ci/mkdocs/mkdocs.yaml -d "$PWD/../dest/docs"
- name: Commit changes
shell: bash
working-directory: dest
run: |
git config user.name "bjw-s-bot[bot]"
git config user.email "bjw-s-bot <87358111+bjw-s-bot[bot]@users.noreply.github.com>"
git add docs
git commit -m "Updated docs from ref: $GITHUB_SHA"
git push

3
.gitignore vendored
View file

@ -4,3 +4,6 @@ charts/**/charts/
# Testing
__snapshot__/
# Docs
_site/

22
.taskfiles/docs.yaml Normal file
View file

@ -0,0 +1,22 @@
---
version: "3"
vars:
MKDOCS_CONFIG_FILE: .ci/mkdocs/mkdocs.yaml
tasks:
build:
desc: >
Build documentation using mkdocs
cmds:
- mkdocs build --config-file ./.ci/mkdocs/mkdocs.yaml
silent: true
serve:
desc: >
Start development server on http://localhost:{{ .PORT }} using mkdocs
vars:
PORT: 8000
cmds:
- mkdocs serve --config-file ./.ci/mkdocs/mkdocs.yaml --dev-addr localhost:{{ .PORT }} --livereload
silent: true

1
Taskfile.yaml
View file

@ -7,6 +7,7 @@ vars:
includes:
charts: .taskfiles/charts.yaml
docs: .taskfiles/docs.yaml
precommit: .taskfiles/precommit.yaml
tasks:

10
charts/library/common/README.md
View file

@ -33,7 +33,7 @@ dependencies:
repository: https://bjw-s.github.io/helm-charts/
```
For more information, take a look at the [Docs](http://docs.k8s-at-home.com/our-helm-charts/common-library/).
For more information, take a look at the [Docs](http://bjw-s.github.io/helm-charts/docs/common-library/introduction/).
## Configuration
@ -51,7 +51,7 @@ N/A
|-----|------|---------|-------------|
| additionalContainers | object | `{}` | Specify any additional containers here as dictionary items. Each additional container should have its own key. Helm templates can be used. |
| addons | object | See below | The common chart supports several add-ons. These can be configured under this key. |
| addons.codeserver | object | See values.yaml | The common library supports adding a code-server add-on to access files. It can be configured under this key. For more info, check out [our docs](http://docs.k8s-at-home.com/our-helm-charts/common-library-add-ons/#code-server) |
| addons.codeserver | object | See values.yaml | The common library supports adding a code-server add-on to access files. It can be configured under this key. For more info, check out [our docs](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-add-ons/##code-server) |
| addons.codeserver.args | list | `["--auth","none"]` | Set codeserver command line arguments. Consider setting --user-data-dir to a persistent location to preserve code-server setting changes |
| addons.codeserver.enabled | bool | `false` | Enable running a code-server container in the pod |
| addons.codeserver.env | object | `{}` | Set any environment variables for code-server here |
@ -83,7 +83,7 @@ N/A
| addons.promtail.logs | list | `[]` | The paths to logs on the volume |
| addons.promtail.loki | string | `""` | The URL to Loki |
| addons.promtail.volumeMounts | list | `[]` | Specify a list of volumes that get mounted in the promtail container. At least 1 volumeMount is required! |
| addons.vpn | object | See values.yaml | The common chart supports adding a VPN add-on. It can be configured under this key. For more info, check out [our docs](http://docs.k8s-at-home.com/our-helm-charts/common-library-add-ons/#wireguard-vpn) |
| addons.vpn | object | See values.yaml | The common chart supports adding a VPN add-on. It can be configured under this key. For more info, check out [our docs](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-add-ons/#wireguard-vpn) |
| addons.vpn.args | list | `[]` | Override the args for the vpn sidecar container |
| addons.vpn.configFile | string | `nil` | Provide a customized vpn configuration file to be used by the VPN. |
| addons.vpn.configFileSecret | string | `nil` | Reference an existing secret that contains the VPN configuration file The chart expects it to be present under the `vpnConfigfile` key. |
@ -165,7 +165,7 @@ N/A
| initContainers | object | `{}` | Specify any initContainers here as dictionary items. Each initContainer should have its own key. The dictionary item key will determine the order. Helm templates can be used. |
| lifecycle | object | `{}` | Configure the lifecycle for the main container |
| nodeSelector | object | `{}` | Node selection constraint [[ref]](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) |
| persistence | object | See below | Configure persistence for the chart here. Additional items can be added by adding a dictionary key similar to the 'config' key. [[ref]](http://docs.k8s-at-home.com/our-helm-charts/common-library-storage) |
| persistence | object | See below | Configure persistence for the chart here. Additional items can be added by adding a dictionary key similar to the 'config' key. [[ref]](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-storage) |
| persistence.config | object | See below | Default persistence for configuration files. |
| persistence.config.accessMode | string | `"ReadWriteOnce"` | AccessMode for the persistent volume. Make sure to select an access mode that is supported by your storage provider! [[ref]](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) |
| persistence.config.enabled | bool | `false` | Enables or disables the persistence item |
@ -232,7 +232,7 @@ N/A
## Support
- See the [Docs](https://docs.k8s-at-home.com/our-helm-charts/getting-started/)
- See the [Docs](http://bjw-s.github.io/helm-charts/docs/)
- Open an [issue](https://github.com/bjw-s/helm-charts/issues/new/choose)
- Join the k8s-at-home [Discord](https://discord.gg/sTMX7Vh) community

2
charts/library/common/README.md.gotmpl
View file

@ -59,7 +59,7 @@ Read through the [values.yaml](./values.yaml) file. It has several commented out
{{- define "custom.support" -}}
## Support
- See the [Docs](https://docs.k8s-at-home.com/our-helm-charts/getting-started/)
- See the [Docs](http://bjw-s.github.io/helm-charts/docs/)
- Open an [issue](https://github.com/bjw-s/helm-charts/issues/new/choose)
- Join the k8s-at-home [Discord](https://discord.gg/sTMX7Vh) community
{{- end -}}

3
charts/library/common/README_CONFIG.md.gotmpl
View file

@ -25,5 +25,6 @@ dependencies:
repository: {{ template "custom.helm.url" }}
```
For more information, take a look at the [Docs](http://docs.k8s-at-home.com/our-helm-charts/common-library/).
For more information, take a look at the [Docs](http://bjw-s.github.io/helm-charts/docs/common-library/introduction/).
{{- end -}}
{{ "" }}

6
charts/library/common/values.yaml
View file

@ -357,7 +357,7 @@ ingress:
# -- Configure persistence for the chart here.
# Additional items can be added by adding a dictionary key similar to the 'config' key.
# [[ref]](http://docs.k8s-at-home.com/our-helm-charts/common-library-storage)
# [[ref]](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-storage)
# @default -- See below
persistence:
# -- Default persistence for configuration files.
@ -477,7 +477,7 @@ resources: {}
addons:
# -- The common chart supports adding a VPN add-on. It can be configured under this key.
# For more info, check out [our docs](http://docs.k8s-at-home.com/our-helm-charts/common-library-add-ons/#wireguard-vpn)
# For more info, check out [our docs](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-add-ons/#wireguard-vpn)
# @default -- See values.yaml
vpn:
# -- Enable running a VPN in the pod to route traffic through a VPN
@ -609,7 +609,7 @@ addons:
# protocol: TCP
# -- The common library supports adding a code-server add-on to access files. It can be configured under this key.
# For more info, check out [our docs](http://docs.k8s-at-home.com/our-helm-charts/common-library-add-ons/#code-server)
# For more info, check out [our docs](https://bjw-s.github.io/helm-charts/docs/common-library/common-library-add-ons/##code-server)
# @default -- See values.yaml
codeserver:
# -- Enable running a code-server container in the pod

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).

40
docs/index.md Normal file
View file

@ -0,0 +1,40 @@
# Welcome
Welcome to the documentation for the [bjw-s Helm charts](https://github.com/bjw-s/helm-charts) project.
## Getting started
[Helm](https://helm.sh) must be installed to use the charts in this repository.
Refer to Helm's [documentation](https://helm.sh/docs/) to get started.
## Installation
```sh
helm repo add bjw-s http://bjw-s.github.io/helm-charts/
```
You can then run `helm search repo bjw-s` to see the charts.
## How do I find people running Kubernetes at home?
### Discord
Join the k8s-at-home [Discord](https://discord.gg/sTMX7Vh) community on Discord.
### Repository topics
Have a look at people running Kubernetes at home
[on GitHub](https://github.com/topics/k8s-at-home?o=desc&s=updated) and
<!-- Disable link check because it requires login -->
<!-- markdown-link-check-disable-next-line -->
[on GitLab](https://gitlab.com/search?search=k8s-at-home).
### Awesome Home Kubernetes
[Checkout](https://github.com/k8s-at-home/awesome-home-kubernetes) our curation
of projects and resources involving running Kubernetes at home.
## License
This project is licensed under the terms of the Apache 2.0 License license.