Files
2026-10-29 16:53:11 -04:00

187 lines
11 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).