187 lines
11 KiB
Markdown
Executable File
187 lines
11 KiB
Markdown
Executable File
# ansible-role-discourse
|
||
|
||
Reusable Ansible role to deploy Discourse on Kubernetes using the official
|
||
[`discourse/base`](https://hub.docker.com/r/discourse/base) image **through the
|
||
official `discourse_docker` launcher build process**. `discourse/base` is the
|
||
upstream base/build image, not a fully configured forum container. The launcher
|
||
combines it with the web templates, a Discourse Git revision, and plugins to
|
||
produce `local_discourse/app`; the role tags and pushes that resulting app image
|
||
for Kubernetes to run.
|
||
|
||
The role manages the Kubernetes namespace, app credentials, PostgreSQL and
|
||
Redis StatefulSets, their PVCs, the Discourse web Deployment and Service,
|
||
optional Ingress, and optional Tor `OnionService`. PostgreSQL and Redis are
|
||
separate internal services; Discourse uploads/backups/logging use a persistent
|
||
`/shared` claim. The forum is deliberately one replica with `Recreate` rollout
|
||
because the official image uses one writable shared directory and its built-in
|
||
web/worker supervision model.
|
||
|
||
## Requirements
|
||
|
||
- Ansible Core 2.16–2.19; install Python packages from `requirements.txt` and
|
||
the `kubernetes.core` collection from `requirements.yml`.
|
||
- Kubernetes API access from the Ansible controller (`kubeconfig` or
|
||
`K8S_AUTH_*` settings) and a StorageClass that supports the configured claims.
|
||
- For image builds, a **Linux** Ansible controller with Docker Engine, Git, and
|
||
registry push access already configured. The role runs the official
|
||
`discourse_docker/launcher bootstrap app` locally, then tags/pushes
|
||
`local_discourse/app` to `discourse_image`. No registry password is accepted
|
||
by the role; authenticate Docker outside Ansible. The cluster needs an image
|
||
pull secret if the target registry is private.
|
||
- Ingress controller/cert-manager and DNS for optional ingress; the Tor
|
||
operator and its OnionService CRD for optional onion access.
|
||
- Encrypted backups of the database **and uploads**, stored outside the
|
||
cluster, with regular restore tests. The role does not move Bitnami PVC data
|
||
or perform Discourse's admin backup restore workflow.
|
||
|
||
## Bitnami migration for eom.dev
|
||
|
||
Use [playbooks/migrate-eom.yml](playbooks/migrate-eom.yml) for the one-time
|
||
migration. It creates a separate `discourse-next` namespace and leaves the
|
||
Bitnami `discourse` namespace, release, and PVCs alone during preparation. The
|
||
first deployment has no ingress or onion route, so the existing site keeps
|
||
serving while you restore and test the replacement.
|
||
|
||
### 1. Prepare and verify a backup
|
||
|
||
1. Inventory the live Bitnami release: actual Discourse and PostgreSQL versions,
|
||
PVC names/classes, storage capacity, SMTP/OIDC/LDAP settings, plugins, and
|
||
ingress/TLS and OnionService configuration. The role cannot infer these
|
||
accurately from the old chart task.
|
||
2. Take a Discourse application backup that includes uploads, download it, and
|
||
encrypt it off-cluster. Restore that backup in a disposable test instance
|
||
first. Keep the old Kubernetes data untouched.
|
||
3. Choose and test the target Discourse revision, PostgreSQL image/major,
|
||
external plugin refs, and registry tag. The old application is 3.4.7; do not
|
||
assume the newest revision or an arbitrary old Git revision is a safe restore
|
||
target. Verify the backup's restore/version compatibility.
|
||
4. Install the role dependencies, select the intended kube context, and
|
||
provide the encrypted site variables described below. Authenticate Docker
|
||
to the image registry on the Linux controller.
|
||
|
||
### 2. Build and deploy the isolated target
|
||
|
||
The EOM playbook requires explicit acknowledgement that the backup was tested.
|
||
After completing the steps above, run the migration playbook with
|
||
`discourse_migration_backup_verified=true` and `discourse_backup_confirmed=true`
|
||
from your encrypted/approved deployment variables. Start with `--syntax-check`
|
||
and `--check`; do not use `--diff` with secret-bearing resources. Then run the
|
||
playbook normally. It builds with the official launcher, pushes the configured
|
||
image tag, and deploys the isolated Kubernetes resources.
|
||
|
||
The first run does **not** copy or reuse Bitnami PostgreSQL files. Wait for the
|
||
new forum to become Ready, then use the Discourse admin backup/restore flow to
|
||
restore the tested archive, which carries the database and uploads. You can
|
||
access the isolated Service via a temporary `kubectl port-forward` to
|
||
`service/discourse` in namespace `discourse-next`. Verify login, admin access,
|
||
uploads, email, billing/subscriptions, OIDC callback
|
||
`/auth/oidc/callback`, LDAP, ActivityPub, Prometheus, webhooks, and forum URLs.
|
||
Reapply/check plugin configuration and external credentials; plugins alone do
|
||
not migrate their settings or secrets.
|
||
|
||
### 3. Cut over
|
||
|
||
Once the restored forum is accepted, schedule downtime and stop writes to the
|
||
old forum. Take and verify the final backup, restore it into `discourse-next`,
|
||
and check the target again. Then run the same migration playbook with
|
||
`discourse_migration_cutover=true`, `discourse_ingress_enabled=true`, and
|
||
`discourse_onion_enabled=true`, while setting `discourse_build_enabled=false`.
|
||
This explicit cutover waits for the target to be Ready, scales the old Bitnami
|
||
Deployment to zero, removes its Ingress and optional OnionService, and creates
|
||
the target routes. The old release and PVCs remain for rollback; do not uninstall
|
||
the release or delete claims until the rollback/retention period has elapsed.
|
||
The old Deployment name and Ingress name default to `discourse`; override the
|
||
`discourse_migration_source_*` variables if the live Helm release uses different
|
||
names. Verify the actual rendered resource names before cutover.
|
||
|
||
The cutover action affects only the named old Deployment, Ingress, and optional
|
||
OnionService. It does not uninstall Helm, scale down PostgreSQL/Redis, or delete
|
||
any source PVC. Keep a tested rollback plan: traffic can be returned to the old
|
||
release, but it may need to be scaled back up and the old Ingress/OnionService
|
||
recreated. Avoid accepting writes on both instances.
|
||
The Tor operator may issue a new `.onion` address when the `OnionService` moves
|
||
to the new namespace. Preserve its identity only by following that operator's
|
||
documented key/Secret migration procedure; otherwise publish the newly assigned
|
||
address after cutover.
|
||
The old EOM Bitnami task is now a retirement guard, and the shared EOM Tor task
|
||
no longer reconciles Discourse. Do not re-enable the old Helm task after
|
||
cutover.
|
||
|
||
### EOM variables and secrets
|
||
|
||
Site-specific settings are deliberately kept in the EOM playbooks, not role
|
||
defaults. Supply the following through encrypted inventory/group vars or an
|
||
Ansible Vault file; never commit the secret values:
|
||
|
||
- `vault_discourse_image`: immutable registry destination, including tag, for
|
||
example `registry.example.invalid/community/discourse:<tested-build>`.
|
||
- `vault_discourse_application_version`: tested Discourse Git revision to
|
||
build with the current official templates.
|
||
- `vault_discourse_launcher_revision`: reviewed commit of the official
|
||
`discourse_docker` repository used for the launcher and templates.
|
||
- `vault_discourse_postgres_image`: pinned PostgreSQL image. Match the selected
|
||
target version to the tested restore plan; do not reuse a data directory
|
||
across PostgreSQL major versions.
|
||
- `vault_discourse_redis_image`: pinned Redis image used by the migration and
|
||
subsequent deploys.
|
||
- `vault_discourse_database_password`, `vault_discourse_redis_password`, and
|
||
`vault_discourse_smtp_password`: unique credentials, not reused from the
|
||
Bitnami deployment.
|
||
- `vault_discourse_plugin_refs`: mapping with reviewed commit/tag refs for
|
||
`docker_manager`, `activity_pub`, `ldap_auth`, and `prometheus`.
|
||
- Optional `vault_discourse_image_pull_secrets`: Kubernetes Secret names for a
|
||
private image registry.
|
||
|
||
Current upstream Discourse bundles several plugins previously cloned from
|
||
GitHub (including subscriptions, OIDC, math, post-voting, reactions, and the ad
|
||
plugin). Do not clone those into a current image; verify the bundled plugin list
|
||
for the chosen app revision. LDAP auth, ActivityPub, and Prometheus are external
|
||
in this site's configuration and need compatibility testing and pinned refs.
|
||
|
||
### Secrets and Kubernetes access
|
||
|
||
Kubernetes Secret manifests are created from Vault-backed variables and tasks
|
||
suppress secret output. Kubernetes Secrets are base64-encoded, not encrypted by
|
||
default: enable API-at-rest encryption, restrict RBAC, and avoid logging
|
||
rendered Secret resources. The launcher build template uses only a throwaway
|
||
placeholder for the DB/Redis password; runtime credentials are injected from
|
||
Kubernetes Secrets. The official Discourse image runs its runit supervisor as
|
||
root and needs a small capability set for service-user switching, volume
|
||
ownership, and binding port 80; the Pod drops all other capabilities and uses
|
||
the runtime-default seccomp profile. Enforce an appropriate Pod Security policy
|
||
for this workload rather than assuming it satisfies the `restricted` profile.
|
||
|
||
## Ongoing deployment and upgrades
|
||
|
||
Use [playbooks/deploy-eom.yml](playbooks/deploy-eom.yml) after cutover. It
|
||
reconciles the same namespace and resource names against the configured image
|
||
and keeps ingress/Tor enabled. Do not change the app image tag to a new build
|
||
until that image has been built and pushed.
|
||
|
||
For an intentional app/plugin upgrade, test the target revisions against a
|
||
restored staging backup, take a fresh encrypted production backup, then run the
|
||
EOM playbook with `discourse_build_enabled=true` and
|
||
`discourse_backup_confirmed=true`. Change `vault_discourse_application_version`,
|
||
`vault_discourse_launcher_revision`, plugin refs, and `vault_discourse_image`
|
||
to a new immutable tag together. The
|
||
role builds via the upstream launcher, pushes, and updates the Deployment. A
|
||
Discourse rebuild may run database migrations; expect downtime and retain the
|
||
previous image and backups for rollback.
|
||
|
||
Generic role defaults and optional behaviors are in
|
||
[defaults/main.yml](defaults/main.yml). Instances default to a private
|
||
ClusterIP Service and disabled ingress/Tor. The role refuses multi-replica
|
||
configuration, supports configurable storage/classes/resources/node placement,
|
||
and never deletes PVCs. Scaling, PostgreSQL major upgrades, backup scheduling,
|
||
network policies, and external ingress/TLS setup remain operator responsibilities.
|
||
|
||
## Tests
|
||
|
||
`tests/run.sh` checks playbook syntax and renders role manifests locally without
|
||
connecting to a cluster. Use the supplied test Dockerfile on a controller with
|
||
Docker, or install dependencies and run the script directly.
|
||
|
||
## License
|
||
|
||
BSD-3-Clause; see [LICENSE](LICENSE).
|