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

feat(docs): Migrate to mdbook

Browse source
This commit is contained in:
Bᴇʀɴᴅ Sᴄʜᴏʀɢᴇʀs 2023-01-10 11:47:16 +01:00
parent bddb5685ab
commit c637f2b7c2
No known key found for this signature in database
GPG key ID: BC5E2BD907F9A8EC
30 changed files with 1614 additions and 435 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/src/SUMMARY.md Normal file
View file

@ -0,0 +1,26 @@
# Summary
[Introduction](introduction.md)
---
# Helm Charts
- [Common Library](common-library/introduction.md)
- [Add-ons](common-library/add-ons/index.md)
- [code-server](common-library/add-ons/code-server/index.md)
- [Storage](common-library/storage/index.md)
- [Permissions](common-library/storage/permissions.md)
- [Storage types](common-library/storage/types.md)
- [PersistentVolumeClaim](common-library/storage/types/pvc.md)
- [EmptyDir](common-library/storage/types/emptydir.md)
- [HostPath](common-library/storage/types/hostpath.md)
- [ConfigMap](common-library/storage/types/configmap.md)
- [Secret](common-library/storage/types/secret.md)
- [NFS share](common-library/storage/types/nfs-share.md)
- [Custom](common-library/storage/types/custom.md)
- [How to...](common-library/howto/index.md)
- [Multiple subPaths for 1 volume](common-library/howto/multiple-subpath.md)
- [Helm templates](common-library/howto/helm-templates.md)
- [App Template](app-template/introduction.md)

30
docs/src/app-template/introduction.md Normal file
View file

@ -0,0 +1,30 @@
# App Template
## Background
Since Helm [library charts](https://helm.sh/docs/topics/library_charts/) cannot be
installed directly I have created a companion chart for the [common library](../common-library/introduction.md).
## Usage
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](../common-library/introduction.md)
and its [`values.yaml`](https://github.com/bjw-s/helm-charts/tree/main/charts/library/common/values.yaml) for
more information about the available configuration options.
#### Examples
This is an example `values.yaml` file that would deploy the [vaultwarden](https://github.com/dani-garcia/vaultwarden)
application. For more deployment examples, check out the [`examples` folder](https://github.com/bjw-s/helm-charts/tree/main/examples/).
```yaml
{{ #include ../../../examples/helm/values.yaml }}
```
## Source code
The source code for the app template chart can be found
[here](https://github.com/bjw-s/helm-charts/tree/main/charts/other/app-template).

47
docs/src/common-library/add-ons/code-server/index.md Normal file
View file

@ -0,0 +1,47 @@
# 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.
```admonish 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
```

5
docs/src/common-library/add-ons/index.md Normal file
View file

@ -0,0 +1,5 @@
# 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.

45
docs/src/common-library/howto/helm-templates.md Normal file
View file

@ -0,0 +1,45 @@
# Helm templates
Some fields in the common library `values.yaml` allow the use of Helm templates for their values.
This is often indicated by a remark similar to `Helm template enabled` in the field description.
This feature allows you to have the value of that key set to the output of the given Helm template.
## Example:
Given the following `values.yaml`
```yaml
image:
repository: k8s.gcr.io/git-sync/git-sync
tag: v3.6.2
additionalContainers:
subcleaner:
name: subcleaner
image: |-
{{ printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) | quote }}
args:
- --repo=https://github.com/KBlixt/subcleaner.git
- --branch=master
- --depth=1
- --root=/add-ons/subcleaner
```
This would render as follows:
```yaml
image:
repository: k8s.gcr.io/git-sync/git-sync
tag: v3.6.2
additionalContainers:
subcleaner:
name: subcleaner
image: k8s.gcr.io/git-sync/git-sync:v3.6.2
args:
- --repo=https://github.com/KBlixt/subcleaner.git
- --branch=master
- --depth=1
- --root=/add-ons/subcleaner
```

3
docs/src/common-library/howto/index.md Normal file
View file

@ -0,0 +1,3 @@
# How to...
Here you can find information on how to accomplish specific scenario's.

43
docs/src/common-library/howto/multiple-subpath.md Normal file
View file

@ -0,0 +1,43 @@
# 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.
```admonish 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
```

38
docs/src/common-library/introduction.md Normal file
View file

@ -0,0 +1,38 @@
# Common library
```admonish note
The Common library chart is not meant to be installed directly, application
charts use the Common library as a dependency.
See the [app template](../../app-template/introduction.md ) for an example how to
deploy it.
```
## 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.
```admonish 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).

4
docs/src/common-library/storage/index.md Normal file
View file

@ -0,0 +1,4 @@
# Common library Storage
This page describes the different ways you can configure and attach storage to charts
using the common library.

6
docs/src/common-library/storage/permissions.md Normal file
View file

@ -0,0 +1,6 @@
# 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.

3
docs/src/common-library/storage/types.md Normal file
View file

@ -0,0 +1,3 @@
# Storage types
Here you can find information on the different types of storage available in the common library chart.

25
docs/src/common-library/storage/types/configmap.md Normal file
View file

@ -0,0 +1,25 @@
# 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 configuration:
```yaml
persistence:
config:
enabled: true
type: configMap
name: mySettings
```
This will mount the contents of the pre-existing `mySettings` configMap to `/config`.

16
docs/src/common-library/storage/types/custom.md Normal file
View file

@ -0,0 +1,16 @@
# 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. |

27
docs/src/common-library/storage/types/emptydir.md Normal file
View file

@ -0,0 +1,27 @@
# 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 configuration:
```yaml
persistence:
config:
enabled: true
type: emptyDir
```
This will create an ephemeral emptyDir volume and mount it to `/config`.

32
docs/src/common-library/storage/types/hostpath.md Normal file
View file

@ -0,0 +1,32 @@
# 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 configuration:
```yaml
persistence:
config:
enabled: true
type: hostPath
hostPath: /dev
```
This will mount the `/dev` folder from the underlying host to `/dev` in the container.

30
docs/src/common-library/storage/types/nfs-share.md Normal file
View file

@ -0,0 +1,30 @@
# NFS Share
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:
```admonish 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 configuration:
```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`.

66
docs/src/common-library/storage/types/pvc.md Normal file
View file

@ -0,0 +1,66 @@
# 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](#dynamically-provisioned)
- [Existing claim](#existing-claim)
## 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 configuration:
```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 configuration:
```yaml
persistence:
config:
enabled: true
type: pvc
existingClaim: myAppData
```
This will mount an existing PVC named `myAppData` to `/config`.

25
docs/src/common-library/storage/types/secret.md Normal file
View file

@ -0,0 +1,25 @@
# 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 configuration:
```yaml
persistence:
config:
enabled: true
type: secret
name: mySecret
```
This will mount the contents of the pre-existing `mySecret` Secret to `/config`.

44
docs/src/introduction.md Normal file
View file

@ -0,0 +1,44 @@
# 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 search the charts.
## Support
If you like this project, please consider supporting my work through my [GitHub sponsorship page](https://github.com/sponsors/bjw-s?frequency=one-time).
## 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).
### Search
You can use this following [search engine](https://nanne.dev/k8s-at-home-search/) provided by [@whazor](https://github.com/whazor) to search for public
repositories containing any application you might wish to run.
## License
This project is licensed under the terms of the Apache 2.0 License license.