claudeandClaude Opus 5.5 04321c85c3 CI: ansible-lint via the shared reusable workflow
Adds .gitea/workflows/lint.yaml calling
DevOps/software-infrastructure's reusable-ansible-role-lint.yaml, and a
baseline (.ansible-lint-ignore, 1 file/rule entries) of existing
findings so only new problems fail. Manual-only until the shared runner
is proven stable (#41) and the CI tools image is published (#49).

CI files only; nothing the role deploys changes.

Refs DevOps/software-infrastructure#53

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:16:44 -05:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00
2026-10-29 16:53:11 -04:00

ansible-role-discourse

Reusable Ansible role to deploy Discourse on Kubernetes using the official 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 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 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. 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.

S
Description
Ansible role to deploy Discourse to Kubernetes and migrate away from Bitnami
Readme BSD-3-Clause
47 KiB
Languages
Jinja 94.8%
Dockerfile 3.4%
Shell 1.8%