01. Les données

Pourquoi un opérateur plutôt qu'un StatefulSet#

Une base de données n'est pas un workload comme un autre : elle a un état, un primaire, des réplicas, et un basculement à orchestrer quand le primaire disparaît. Écrire ça soi-même dans un StatefulSet revient à réimplémenter, mal, ce qu'un opérateur fait déjà.

CloudNativePG prend en charge la réplication en flux, l'élection d'un nouveau primaire, les Services -rw / -ro qui suivent les rôles, et le pooler. On lui décrit l'état voulu, il s'occupe du reste.

# k8s/database.yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: task-manager-db
  namespace: task-manager
spec:
  instances: 3                    # 1 primaire + 2 réplicas
  affinity:
    enablePodAntiAffinity: true
    topologyKey: kubernetes.io/hostname
    podAntiAffinityType: required # une instance par nœud, sans exception
  storage:
    size: 1Gi
  bootstrap:
    initdb:
      database: task_manager
      owner: task_manager

Pourquoi required et pas preferred#

C'est le choix le plus lourd de conséquence du fichier, et il mérite d'être explicite.

L’anti-affinité stricte évite de perdre plusieurs instances avec un seul nœud. Le failover dépend aussi de la disponibilité du contrôleur, du contrôle Kubernetes et d’un réplica suffisamment à jour. PostgreSQL en réplication asynchrone ne requiert pas un quorum de deux instances pour servir : ne pas le confondre avec le consensus d’une quorum queue RabbitMQ.

Le pooler : deux pods, mode transaction#

apiVersion: postgresql.cnpg.io/v1
kind: Pooler
metadata:
  name: task-manager-pooler
spec:
  cluster:
    name: task-manager-db
  instances: 2                    # deux processus ; placement sur les nœuds à contrôler
  type: rw
  pgbouncer:
    poolMode: transaction
    parameters:
      max_client_conn: "1000"
      default_pool_size: "20"     # ⚠️ par pod ET par couple (utilisateur, base)

Deux détails qui se paient cher si on les rate :

• default_pool_size se compte par pod et par couple (utilisateur, base). Ici l'application n'en utilise qu'un seul, task_manager sur task_manager : 2 pods à 20 donnent donc une capacité de 40 connexions serveur vers le primaire, dimensionnée sous le max_connections de PostgreSQL (100 par défaut). Ce n'est pas une formule universelle : ajouter un second utilisateur ou une seconde base ouvre un pool de plus, et reserve_pool_size s'y ajoute encore. Passer les poolers à 5 sans y penser, et la base refuse des connexions.
• Le Service s'appelle task-manager-pooler, sans suffixe. Le -rw appartient au Cluster et vise le primaire en direct — c'est celui qu'utilisent les migrations, justement.

Ce que le mode transaction impose au code#

Le pooler prête une connexion serveur pendant une transaction. Une nouvelle transaction peut utiliser une autre connexion ; la continuité de session n’est donc pas garantie.

1. Le cache d'énoncés préparés, désactivé#

# k8s/api-deployment.yaml
- name: APP_DATABASE_URL
  value: "postgresql+asyncpg://task_manager:$(DB_PASSWORD)@task-manager-pooler:5432/task_manager?prepared_statement_cache_size=0"

Le dépôt désactive le cache de requêtes préparées du dialecte SQLAlchemy/asyncpg avec prepared_statement_cache_size=0. Cela ne désactive pas les préparations elles-mêmes. PgBouncer sait gérer les prepared statements nommés au niveau protocole depuis 1.21 si max_prepared_statements est non nul ; PREPARE/EXECUTE SQL restent un autre cas. Voir la FAQ PgBouncer.

2. Un nom d'énoncé unique, et pool_pre_ping#

# backend/src/task_manager/infrastructure/persistence/database.py
return create_async_engine(
    database_url.get_secret_value(),
    pool_pre_ping=True,
    pool_size=pool_size,
    max_overflow=max_overflow,
    connect_args={"prepared_statement_name_func": lambda: f"__asyncpg_{uuid4()}__"},
)

• prepared_statement_name_func — asyncpg nomme ses énoncés de façon incrémentale (__asyncpg_stmt_1__…). Deux clients multiplexés sur la même connexion serveur choisiraient le même nom et déclencheraient un DuplicatePreparedStatementError. Un UUID par énoncé supprime la collision.
• pool_pre_ping teste une connexion à sa sortie du pool SQLAlchemy et remplace celles déjà mortes. Il ne protège ni une transaction en cours ni un arrêt survenant après le ping, et n’est pas spécifique à PgBouncer.

Les migrations contournent le pooler#

Le DDL PostgreSQL est largement transactionnel et peut passer par PgBouncer. Une connexion directe au primaire facilite cependant la maîtrise de la session de migration et de ses opérations hors transaction. C’est le choix du dépôt, pas une obligation générale d’Alembic.

• Alembic ne prend pas automatiquement de verrou consultatif dans ce dépôt. alembic/env.py n’en crée aucun. La connexion directe ne sérialise donc pas deux migrateurs : il faut un verrou explicite ou une exclusion au niveau du déploiement si ce cas est possible.
• CREATE INDEX CONCURRENTLY doit être exécuté hors bloc transactionnel. Dans PostgreSQL 17, ALTER TYPE … ADD VALUE peut être exécuté dans une transaction, mais la nouvelle valeur ne peut être utilisée qu’après commit. Voir ALTER TYPE.
• les SET de session (lock_timeout, search_path) ne sont pas garantis d'une requête à la suivante ;
• une migration doit viser le primaire, explicitement.

Le Job de migration vise donc PostgreSQL en direct :

# k8s/migrate-job.yaml
- name: APP_DATABASE_URL
  value: "postgresql+asyncpg://task_manager:$(DB_PASSWORD)@task-manager-db-rw:5432/task_manager"
- name: APP_INIT_DB
  value: "false"

Trois points valent d'être notés :

• Pas de ?prepared_statement_cache_size=0 : sans pooler, la contrainte disparaît. L'absence est aussi intentionnelle que la présence ailleurs.
• APP_INIT_DB=false : le schéma est piloté par Alembic, jamais par un create_all au démarrage. Les deux mécanismes existent dans le code (ch. 12) ; en cluster, un seul a le droit de s'exécuter.
• Le script attend le Job avant d’appliquer les workloads au premier déploiement. Sur un cluster existant, les pods tournent déjà et un Job Completed ne se relance pas par un simple apply. Une mise à jour exige une nouvelle exécution des migrations et un schéma compatible avec les versions encore actives.

# k8s/deploy.sh — la barrière
kubectl apply -f k8s/migrate-job.yaml
kubectl wait --for=condition=complete job/db-migrate -n task-manager --timeout=180s
kubectl apply -f k8s/api-config.yaml
kubectl apply -f k8s/api-deployment.yaml

Le Job porte backoffLimit: 5 et restartPolicy: OnFailure : une base pas encore prête au premier essai n'échoue pas le déploiement, elle provoque une nouvelle tentative.

Les secrets, générés et jamais écrits#

Le mot de passe de la base n'apparaît nulle part dans le dépôt. CNPG crée le secret task-manager-db-app au bootstrap ; les workloads le référencent :

- name: DB_PASSWORD
  valueFrom:
    secretKeyRef: { name: task-manager-db-app, key: password }
# puis interpolé dans l'URL
- name: APP_DATABASE_URL
  value: "postgresql+asyncpg://task_manager:$(DB_PASSWORD)@task-manager-pooler:5432/..."

Même principe pour RabbitMQ, dont l'opérateur génère rabbitmq-default-user. Le fichier secrets.yaml versionné ne contient que ce qui n'est pas généré — et ses valeurs sont des change-me explicites, pas des secrets déguisés en exemple.

À retenir#

• Une base se confie à un opérateur : failover, réplication et Services suivant les rôles ne se réimplémentent pas à la main.
• L'anti-affinité requise échange de la souplesse de placement contre la garantie qu'un nœud perdu n'emporte qu'une instance.
• default_pool_size se compte par pod et par couple (utilisateur, base) : c'est la somme qui doit rester sous le max_connections de PostgreSQL, pas le chiffre du manifeste.
• Les contraintes du mode transaction dépendent des fonctionnalités utilisées et de la configuration réelle du pooler ; vérifier ensemble le client, le pooler et le serveur.
• Les migrations contournent le pooler et forment une barrière avant tout pod applicatif.
• Les mots de passe sont générés par les opérateurs, jamais versionnés.