Synapse sur GKE Autopilot — Guide de Lab
Vue d'ensemble
Temps estimé : 45 à 90 minutes
Synapse est le homeserver Matrix de référence — le serveur open source pour Matrix, une norme ouverte pour la communication décentralisée, fédérée et en temps réel. Ce lab vous guide à travers le cycle de vie opérationnel complet du module Synapse sur GKE Autopilot sur Google Cloud : déployez-le, accédez-y et vérifiez-le, enregistrez un administrateur et connectez-vous via l'API Matrix, exécutez-le au quotidien, observez-le, diagnostiquez les problèmes courants et supprimez-le.
Le lab se concentre sur l'exploitation du module GKE et de la plateforme Google Cloud, et non sur les fonctionnalités du produit Matrix. Pour la liste complète des services provisionnés et de chaque entrée de configuration (organisée par groupe), consultez le Guide de configuration — ce lab ne duplique délibérément pas ces détails afin qu'ils restent précis au fil du temps.
Objectifs
À la fin de ce lab, vous serez capable de :
- Déployer le module depuis la plateforme RAD et localiser les ressources qu'il provisionne.
- Vous connecter au cluster GKE et accéder à la charge de travail en cours d'exécution.
- Enregistrer un utilisateur administrateur et vous connecter via l'API client Matrix ; connecter Element.
- Effectuer des opérations de jour 2 — inspecter, mettre à l'échelle, mettre à jour et gérer les secrets et le stockage.
- Observer la charge de travail avec Cloud Logging et Cloud Monitoring.
- Diagnostiquer et résoudre les problèmes de déploiement et d'exécution les plus courants.
- Supprimer proprement le déploiement.
Prérequis
- Services_GCP (fournit le VPC, le cluster GKE Autopilot, Cloud SQL, Artifact Registry et les comptes de service partagés dont dépend ce module). Vous n'avez pas besoin de le déployer vous-même au préalable — la plateforme détecte automatiquement s'il existe déjà dans le projet cible et le provisionne avant ce module si ce n'est pas le cas (voir Tâche 1).
- Un projet Google Cloud avec la facturation activée.
- gcloud CLI et kubectl installés ;
gcloud auth loginetgcloud auth application-default loginterminés. - Rôle IAM de Propriétaire de projet (ou équivalent) sur le projet.
- Vous apportez votre propre projet ? Avant le premier déploiement, la boîte de dialogue de confirmation du déploiement vous demande de prouver que vous le contrôlez (Obtenir le code de vérification, exécutez les commandes qu'elle affiche en tant que Propriétaire du projet, puis Vérifier) et de donner au compte de service de déploiement RAD le rôle de Propriétaire. Un projet créé par RAD pour vous n'a besoin de rien de tout cela.
- Mode avancé pour les modifications ultérieures. Le formulaire de création ne demande que la première page d'entrées (et, dans un projet créé par RAD pour vous, guère plus que le nom du locataire et la région). Toutes les autres entrées du Guide de configuration — y compris les entrées de mise à l'échelle et de version dans les tâches de jour 2 — sont modifiées ultérieurement avec Update sur la page du déploiement après avoir coché Enable advanced mode, ouvert à tous les comptes tant que les builds sont inclus dans le prix (dans un environnement de lab, seul un administrateur peut l'utiliser). Les mises à jour n'entraînent jamais de frais de module.
- Accès à la plateforme RAD avec l'autorisation de déployer des modules dans le projet.
- Un domaine que vous contrôlez pour
server_namesi vous avez l'intention de fédérer (définissez-le avant le premier déploiement — il est immuable).
Définissez ces variables shell une fois ; chaque tâche ci-dessous les réutilise :
export PROJECT="<your-gcp-project-id>"
export REGION="us-central1" # the region you deploy into
Tâche 1 — Déployer le module [Automatisé]
-
Ouvrez Solutions → Catalogue de solutions → Modules RAD dans la navigation supérieure de la plateforme RAD, ouvrez Synapse (GKE) depuis la liste Modules de plateforme, choisissez Formulaire de configuration sous Comment souhaitez-vous configurer ce déploiement ? (le formulaire s'ouvre sur l'Assistant conversationnel si vous détenez des crédits achetés ou si vous êtes un partenaire ou un administrateur), définissez
project_id, et — surtout — définissezserver_namesur votre domaine réel (il est intégré à chaque ID utilisateur et est immuable après le premier démarrage). Passez en revue le reste des entrées ; le Guide de configuration documente chaque entrée par groupe, avec les valeurs par défaut. Cliquez sur Déployer le module, examinez le coût estimé dans la boîte de dialogue Confirmation de déploiement lorsqu'elle apparaît et cliquez sur Soumettre (si la boîte de dialogue ajoute ensuite une étape de confirmation, comme la vérification d'un projet que vous apportez, complétez-la et cliquez sur Confirmer), ce qui ouvre la page d'état du déploiement avec des logs en temps réel. -
La plateforme déploie la charge de travail dans le cluster GKE Autopilot, provisionne une base de données Cloud SQL (PostgreSQL 15) avec ses secrets Secret Manager (le secret partagé d'enregistrement et le mot de passe de la base de données), un bucket de données Cloud Storage et un volume NFS pour la clé de signature et les médias, construit l'image du conteneur et exécute un job unique
db-initqui crée la base de données avec la collation obligatoireC. Il n'y a pas de job de migration séparé — Synapse construit son propre schéma au premier démarrage. Les premiers déploiements prennent environ 20 à 35 minutes (la création de Cloud SQL domine). -
Connectez-vous au cluster et découvrez l'espace de noms avec des filtres agnostiques au nom :
CLUSTER=$(gcloud container clusters list --project="$PROJECT" --format="value(name)" --limit=1)
gcloud container clusters get-credentials "$CLUSTER" --region="$REGION" --project="$PROJECT"
NS=$(kubectl get ns -o name | grep synapse | head -1 | cut -d/ -f2)
echo "Cluster: $CLUSTER Namespace: $NS"
kubectl get all -n "$NS"
Tâche 2 — Accéder et vérifier ; enregistrer un administrateur [Manuel]
-
Confirmez que la charge de travail est en cours d'exécution et trouvez son adresse externe :
kubectl get pods,svc -n "$NS"
EXTERNAL_IP=$(kubectl get svc -n "$NS" \
-o jsonpath='{.items[?(@.spec.type=="LoadBalancer")].status.loadBalancer.ingress[0].ip}')
echo "External IP: $EXTERNAL_IP" -
Confirmez que le homeserver est sain. Synapse sert un
200 OKnon authentifié à/healthsur le port 8008, et l'API client Matrix annonce ses versions de spécification prises en charge :curl -s "http://${EXTERNAL_IP}/health" # expect: OK
curl -s "http://${EXTERNAL_IP}/_matrix/client/versions" # expect JSON with a "versions" array -
Le premier utilisateur administrateur est déjà enregistré. Le job d'initialisation
create-admindu module exécuteregister_new_matrix_user -u admin -apour vous, en utilisant le mot de passe superutilisateur généré et conservé dans Secret Manager. Lisez ce mot de passe :PW_SECRET=$(gcloud secrets list --project="$PROJECT" \
--filter="name~synapse AND name~superuser-password" --format="value(name)" --limit=1)
gcloud secrets versions access latest --secret="$PW_SECRET" --project="$PROJECT"L'enregistrement en libre-service est désactivé par défaut, alors créez tout utilisateur supplémentaire hors bande avec
register_new_matrix_user, exécuté depuis l'intérieur du pod oùhomeserver.yaml(avec son secret partagé) est présent :POD=$(kubectl get pods -n "$NS" -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n "$NS" "$POD" -- \
register_new_matrix_user -c /data/homeserver.yaml -u <new-user> -p '<strong-password>' \
http://localhost:8008 -
Connectez-vous via l'API Matrix pour confirmer que le compte fonctionne de bout en bout :
curl -s -XPOST "http://${EXTERNAL_IP}/_matrix/client/v3/login" \
-H 'Content-Type: application/json' \
-d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"admin"},"password":"<the-password>"}'
# A successful response returns an access_token, device_id, and user_id (@admin:<server_name>). -
Connectez un client. Ouvrez l'application web Element, choisissez Sign in → Edit le homeserver, et entrez l'URL de votre homeserver (l'IP externe ou, de préférence, un domaine personnalisé correspondant à
server_name). Connectez-vous en tant queadmin.
Tâche 3 — Opérer et maintenir en fonctionnement (Jour 2) [Manuel]
-
Inspectez la charge de travail — déploiement, pods et l'autoscaler horizontal :
kubectl get deploy,pods,hpa,pdb,pvc -n "$NS"
kubectl describe deploy -n "$NS" -
Gardez au moins un réplica. GKE ne met pas à l'échelle à zéro, ce qui convient à un homeserver fédérateur qui doit rester accessible ;
min_instance_count = 1et un PodDisruptionBudget le maintiennent disponible lors des mises à jour de nœuds. La mise à l'échelle est une modification de configuration via Update, et non unkubectl scalemanuel (une modification manuelle est annulée lors du prochain apply). L'affinité de session (ClientIP) maintient les requêtes d'un client sur le même pod. -
Mettez à jour la version de l'application en modifiant l'entrée de version dans la plateforme RAD et en l'appliquant via Update ; une nouvelle image est construite et une mise à jour progressive remplace les pods (les charges de travail basées sur NFS utilisent une stratégie
Recreatepour éviter que deux pods ne se disputent le même répertoire de données). Synapse applique lui-même les mises à niveau de schéma au démarrage. -
Gérez les secrets, le stockage et les jobs :
kubectl get secrets -n "$NS"
gcloud secrets list --project="$PROJECT" --filter="name~synapse"
kubectl get jobs -n "$NS" # db-init and any scheduled jobs -
Ouvrez une session de base de données pour l'inspection ou la maintenance — et confirmez la collation :
INSTANCE=$(gcloud sql instances list --project="$PROJECT" --format="value(name)" --limit=1)
# Role and database are tenant-prefixed (e.g. synapsedemo426161cf) — not the bare app name.
DB_USER=$(gcloud sql users list --instance="$INSTANCE" --project="$PROJECT" \
--format="value(name)" --filter="name~^synapse" --limit=1)
gcloud sql connect "$INSTANCE" --user="$DB_USER" --project="$PROJECT"
# SELECT datname, datcollate, datctype FROM pg_database WHERE datname = 'synapse';
Tâche 4 — Observer : Logging et Monitoring [Manuel]
-
Logs — depuis
kubectlou l'Explorateur de logs :kubectl logs -n "$NS" deploy/"$(kubectl get deploy -n "$NS" -o jsonpath='{.items[0].metadata.name}')" --tail=50Filtre de l'Explorateur de logs :
resource.type="k8s_container" AND resource.labels.namespace_name="<namespace>". -
Monitoring — ouvrez les tableaux de bord GKE / Kubernetes et examinez l'utilisation du CPU et de la mémoire des pods, les nombres de redémarrages et les métriques de requêtes. Le module peut provisionner un test de disponibilité (lorsqu'il est activé —
uptime_check_configpar défaut àenabled = false) contre/, et non/health; examinez Monitoring → Tests de disponibilité et Alerting → Stratégies.
Tâche 5 — Dépannage et débogage [Manuel]
Techniques durables pour les modes de défaillance que vous êtes le plus susceptible de rencontrer. Il s'agit de diagnostics au niveau de la plateforme et ils ne changent pas avec les versions de Synapse.
- Pod non prêt / CrashLoopBackOff : inspectez les événements et les logs.
Les
startup_probeetliveness_probepar défaut au chemin/(cette variante GKE remplace le propre défautSynapse_Commonde/health) et la sonde de disponibilité cible/health, le tout sur le port 8008 — une inadéquation du port du conteneur ou du port de la sonde fait que la sonde atteint un port mort et le pod ne devient jamais prêt même si Synapse est sain.kubectl describe pod -n "$NS" <pod> # Events show scheduling/probe/mount errors
kubectl logs -n "$NS" <pod> --previous # logs from the crashed container Database has incorrect values for … collation: la base de données n'a pas été créée avec la collationC. Confirmez que le jobdb-inita été exécuté ; réexécutez-le ou recréez la base de données (vide) avecLC_COLLATE='C' LC_CTYPE='C'.kubectl get jobs -n "$NS"
kubectl logs -n "$NS" job/<db-init-job>- Fédération rompue / sessions d'appareil perdues après un redéploiement :
la clé de signature a été régénérée car le répertoire de données n'était pas
persistant. Soit utilisez un PVC StatefulSet (
stateful_pvc_mount_pathpar défaut à/data), soit conservezenable_nfs = trueetnfs_mount_path = "/data"(les deux valeurs par défaut) — tout autre chemin de montage ne correspond pas au répertoire de données du point d'entrée (SYNAPSE_DATA_DIR = "/data"), de sorte que la clé de signature n'atterrirait pas sur le montage persistant et ne survivrait pas aux redémarrages des pods. - Erreurs de connexion à la base de données : confirmez que l'instance
Cloud SQL est
RUNNABLE, que le secret du mot de passe de la base de données est matérialisé dans l'espace de noms et que le job d'initialisation est terminé. - Pod en attente / pas d'IP externe : vérifiez les événements
kubectl describe podpour les problèmes de ressources ou de quotas, et confirmez que le service LoadBalancer a une IP attribuée. - Erreurs de pull d'image : confirmez que l'image existe dans Artifact Registry et que le compte de service du nœud peut la pull.
Consultez la section Pièges de configuration du Guide de configuration pour
les pièges spécifiques aux paramètres (y compris les règles critiques selon
lesquelles server_name et la clé de signature sont immuables après le premier
démarrage, et que le port du conteneur et les sondes doivent être 8008).
Tâche 6 — Suppression [Automatisé]
Sur la page Déploiements, ouvrez le déploiement et cliquez sur l'icône
Corbeille (Supprimer). La suppression exécute terraform destroy et est
irréversible (l'enregistrement du déploiement est conservé pour l'historique).
Si un déploiement est bloqué et que la plateforme RAD ne peut plus le gérer
(par exemple après des modifications manuelles qui entrent en conflit avec
l'état Terraform), utilisez plutôt Purger (depuis la même boîte de
dialogue Supprimer) — cela supprime le déploiement des enregistrements de
RAD sans détruire les ressources cloud (cela fait oublier le déploiement à
RAD). Cela supprime tout ce que le module a créé — la charge de travail
Kubernetes et l'espace de noms, la base de données Cloud SQL, les secrets
Secret Manager, les buckets GCS, le volume NFS et les images Artifact Registry.
Les ressources appartenant à Services_GCP (le VPC, le cluster GKE, Cloud
SQL partagé, le registre) sont gérées séparément et ne sont pas supprimées ici.
Résumé
| Tâche | Type | Résultat |
|---|---|---|
| 1 — Déployer | Automatisé | Le module déploie la charge de travail GKE, Cloud SQL (PostgreSQL 15, collation C), les secrets, le stockage et exécute l'initialisation de la base de données |
| 2 — Accéder et vérifier | Manuel | Se connecter au cluster ; le contrôle de santé réussit ; enregistrer un administrateur ; se connecter via l'API Matrix ; connecter Element |
| 3 — Opérer | Manuel | Inspecter la charge de travail, mettre à l'échelle, mettre à jour la version, gérer les secrets/le stockage, l'accès à la base de données |
| 4 — Observer | Manuel | Interroger Cloud Logging ; examiner les métriques Cloud Monitoring et le test de disponibilité |
| 5 — Dépannage | Manuel | Diagnostiquer les problèmes de pod, de collation, de clé de signature, de base de données, de job d'initialisation, de planification et de pull d'image |
| 6 — Suppression | Automatisé | La suppression (Corbeille) supprime toutes les ressources du module |
Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.