mastodon/chart/README.md

103 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# Introduction
This is a [Helm](https://helm.sh/) chart for installing Mastodon into a
Kubernetes cluster. The basic usage is:
1. edit `values.yaml` or create a separate yaml file for custom values
1. `helm dep update`
1. `helm install --namespace mastodon --create-namespace my-mastodon ./ -f path/to/additional/values.yaml`
This chart is tested with k8s 1.21+ and helm 3.6.0+.
# Configuration
The variables that _must_ be configured are:
- password and keys in the `mastodon.secrets`, `postgresql`, and `redis` groups; if
left blank, some of those values will be autogenerated, but will not persist
across upgrades.
- SMTP settings for your mailer in the `mastodon.smtp` group.
# Administration
You can run [admin CLI](https://docs.joinmastodon.org/admin/tootctl/) commands in the web deployment.
```bash
kubectl -n mastodon exec -it deployment/mastodon-web -- bash
tootctl accounts modify admin --reset-password
```
or
```bash
kubectl -n mastodon exec -it deployment/mastodon-web -- tootctl accounts modify admin --reset-password
```
# Missing features
Currently this chart does _not_ support:
- Hidden services
- Swift
# Upgrading
Because database migrations are managed as a Job separate from the Rails and
Sidekiq deployments, its possible they will occur in the wrong order. After
upgrading Mastodon versions, it may sometimes be necessary to manually delete
the Rails and Sidekiq pods so that they are recreated against the latest
migration.
# Upgrades in 2.1.0
## ingressClassName and tls-acme changes
The annotations previously defaulting to nginx have been removed and support
for ingressClassName has been added.
```yaml
ingress:
annotations:
kubernetes.io/ingress.class: nginx
kubernetes.io/tls-acme: "true"
```
To restore the old functionality simply add the above snippet to your `values.yaml`,
but the recommendation is to replace these with `ingress.ingressClassName` and use
cert-manager's issuer/cluster-issuer instead of tls-acme.
If you're uncertain about your current setup leave `ingressClassName` empty and add
`kubernetes.io/tls-acme` to `ingress.annotations` in your `values.yaml`.
# Upgrades in 2.0.0
## Fixed labels
Because of the changes in [#19706](https://github.com/mastodon/mastodon/pull/19706) the upgrade may fail with the following error:
```Error: UPGRADE FAILED: cannot patch "mastodon-sidekiq"```
If you want an easy upgrade and you're comfortable with some downtime then
simply delete the -sidekiq, -web, and -streaming Deployments manually.
If you require a no-downtime upgrade then:
1. run `helm template` instead of `helm upgrade`
2. Copy the new -web and -streaming services into `services.yml`
3. Copy the new -web and -streaming deployments into `deployments.yml`
4. Append -temp to the name of each deployment in `deployments.yml`
5. `kubectl apply -f deployments.yml` then wait until all pods are ready
6. `kubectl apply -f services.yml`
7. Delete the old -sidekiq, -web, and -streaming deployments manually
8. `helm upgrade` like normal
9. `kubectl delete -f deployments.yml` to clear out the temporary deployments
## PostgreSQL passwords
If you've previously installed the chart and you're having problems with
postgres not accepting your password then make sure to set `username` to
`postgres` and `password` and `postgresPassword` to the same passwords.
```yaml
postgresql:
auth:
username: postgres
password: <same password>
postgresPassword: <same password>
```
And make sure to set `password` to the same value as `postgres-password`
in your `mastodon-postgresql` secret:
```kubectl edit secret mastodon-postgresql```