Base relationnelle des services de la plateforme avec l'extension pgvector pour les plongements. Serveur unique, ou haute disponibilité avec Patroni : réplication en flux, bascule automatique et élection du leader dans etcd. Un cluster PostgreSQL de la banque peut être connecté à la place.
Généré depuis catalog/services/postgresql.yaml : ne pas modifier à la main.
Résumé
| |
|---|
| Version | 16.15 |
| Usage | installer et configurer |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Plateformes de données |
| Méthodes d'installation | podman, package, python |
| Connexion externe | postgresql |
| Réservé au bac à sable | non |
Licence
| |
|---|
| Identifiant SPDX | PostgreSQL |
| Politique de licence | exception de licence |
| Exception de licence | LEX-001 (en attente de la décision du client) |
| Composant de la plateforme | postgresql |
Paquets et artefacts
Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.
| Type | Paquet | Version | Licence | Détails |
|---|
| image de conteneur | docker.io/pgvector/pgvector | 0.8.7-pg16-bookworm | PostgreSQL | clé d'image postgres, utilisée par postgres, condensé sha256:0dd3149a06e4579a0d70d8fef9945636cd514005e7237deb27f9b67886f8dc4f |
| paquet Python | pixeltable-pgserver | 0.7.1 | PostgreSQL | interpréteurs, par ordre de préférence python3.11, python3.12, python3.10 |
| paquet Python | patroni[etcd3] | 4.1.5 | PostgreSQL | interpréteurs, par ordre de préférence python3.11, python3.12, python3.10 |
| paquet Python | psycopg[binary] | 3.3.2 | PostgreSQL | interpréteurs, par ordre de préférence python3.11, python3.12, python3.10 |
| paquet système | postgresql16-server | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | postgresql16 | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | postgresql16-contrib | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | pgvector_16 | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | patroni | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | patroni-etcd | version du dépôt configuré | PostgreSQL | famille RHEL (dnf) |
| paquet système | postgresql-16 | version du dépôt configuré | PostgreSQL | famille Debian (apt) |
| paquet système | postgresql-client-16 | version du dépôt configuré | PostgreSQL | famille Debian (apt) |
| paquet système | postgresql-16-pgvector | version du dépôt configuré | PostgreSQL | famille Debian (apt) |
| paquet système | patroni | version du dépôt configuré | PostgreSQL | famille Debian (apt) |
| paquet système | python3-etcd | version du dépôt configuré | PostgreSQL | famille Debian (apt) |
Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.
Systèmes et architectures pris en charge
| Méthode | Systèmes d'exploitation | Architectures |
|---|
podman | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
package | famille RHEL (dnf), famille Debian (apt) | x86_64, aarch64 (non restreintes par le descripteur) |
python | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.
Prérequis
Hôte
- au moins 1024 Mo de mémoire (bloquant,
memory).
- au moins 5120 Mo libres pour
/var/lib/navin (avertissement, disk).
- une horloge synchronisée (avertissement,
time_sync).
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|
postgres | sql | 5432/tcp | oui |
postgres | restapi | 8008/tcp (mode ha) | oui |
Services et connexions nécessaires
Détail et résolution : voir Dépendances.
Méthodes et modes d'installation
| Méthode | Défaut | Ce que la méthode utilise |
|---|
podman | oui | les images de conteneur du descripteur, exécutées par Podman sous systemd |
package | - | les paquets système du descripteur, installés par le gestionnaire de paquets de l'hôte |
python | - | un environnement virtuel Python qui contient les paquets Python du descripteur |
Composants
| Composant | Type | Méthodes d'installation | Ports |
|---|
Serveur PostgreSQL (postgres) | maître | podman, package, python | 5432/tcp, 8008/tcp (mode ha) |
Serveur unique (standalone) (par défaut)
Un seul serveur PostgreSQL, sans réplica.
Ce que le mode déploie :
| Composant | Placement |
|---|
postgres | min 1, max 1 |
Haute disponibilité (Patroni) (ha)
2 à 7 membres (3 recommandés) gérés par Patroni : un leader, les autres membres sont des réplicas en flux, bascule automatique par etcd. Méthodes package et python.
Ce que le mode déploie :
| Composant | Placement |
|---|
postgres | min 2, max 7, recommandé 3 |
Installer ce service
L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.
-
Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.
-
Choisissez le service. À l'étape Service, sélectionnez PostgreSQL. La carte affiche la licence PostgreSQL et les dépendances dont l'installation a besoin. Choisissez la Méthode parmi podman, package, python (par défaut podman). Pour enregistrer à la place un service postgresql existant de votre organisation, activez Utiliser un service externe existant.
-
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : standalone (par défaut), ha. Chaque mode déploie les composants listés dans Méthodes et modes d'installation.
-
Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (dcs) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.
-
Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.
-
Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.
-
Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services. Ouvrez le service et choisissez Lancer le test fonctionnel dans la carte Contrôles : Crée une table temporaire sur le leader, écrit puis relit une ligne ; avec pgvector, une colonne vector(3) et une requête du plus proche voisin.
Haute disponibilité
Prérequis
| Prérequis | Doit être hautement disponible | Modes | Description |
|---|
dcs | oui | ha | etcd en mode cluster (3 ou 5 membres, quorum Raft) : Patroni rétrograde le leader quand etcd est injoignable, un membre etcd unique en ferait donc le point de défaillance unique. |
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|
standalone | autonome (standalone) | unique (single) | - | 1 | Un serveur PostgreSQL, restauré depuis ses sauvegardes après une perte. |
ha | ha (ha) | actif-passif (active-passive) | - | 3 | Un leader en lecture écriture et 1 à 6 réplicas en flux ; Patroni promeut le réplica sain le plus avancé quand la clé du leader expire dans etcd, l'ancien leader revient comme réplica (pg_rewind). |
Remarques
- Mode ha : les consommateurs joignent le leader par la liste libpq de tous les membres avec target_session_attrs=read-write (clients PostgreSQL 14 ou plus récents). Pour les clients qui ne prennent qu'une adresse, placer HAProxy devant les membres avec un contrôle HTTP GET /primary sur le port de l'API REST de Patroni : seul le leader répond 200.
- Réplication asynchrone par défaut : une bascule peut perdre les dernières transactions pas encore reçues par le réplica promu, bornées par maximum_lag_on_failover ; synchronous_mode supprime cette perte.
- Le mode ha fonctionne avec les méthodes package et python ; Patroni sans watchdog s'appuie sur la durée de vie de la clé du leader dans etcd.
- Les réglages d'amorçage (max_connections, WAL, ttl, loop_wait, retry_timeout, synchronous_mode) sont écrits dans etcd au premier démarrage ; une modification ultérieure s'applique avec la commande push_settings.
- Un cluster PostgreSQL de la banque qui répond à ses exigences de haute disponibilité peut être connecté à la place (type de connexion postgresql).
Paramètres de configuration
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Port (port) | port | 5432 | - | non | non | non | Port TCP du serveur SQL. |
Port de l'API REST de Patroni (restapi_port) | port | 8008 | - | non | non | non | Port de l'API REST de Patroni de chaque membre (contrôles /liveness, /primary, /replica, état du cluster, bascule). (ha) |
Adresse d'écoute (listen_address) | string | * | - | non | non | non | Adresses sur lesquelles le serveur et l'API REST de Patroni écoutent. (avancé) |
Réglages
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Connexions maximales (max_connections) | int | 200 | min 20, max 5000 | non | non | oui | Nombre maximal de connexions clientes. |
Tampons partagés (shared_buffers_mb) | int | 512 | min 64, MB | non | non | oui | Mémoire du cache de tampons partagés, environ 25 pour cent de la mémoire de l'hôte. (recommandé clamp(round(host.memory_mb * 0.25), 128, 16384)) |
WAL conservés pour les réplicas (wal_keep_size_mb) | int | 1024 | min 0, max 1048576, MB | non | non | non | WAL conservés dans pg_wal pour les réplicas et les sauvegardes (wal_keep_size). |
Sécurité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Mot de passe du superutilisateur (superuser_password) | password | généré | - | non | oui | non | Mot de passe du rôle postgres, utilisé par les commandes de provisionnement, les sauvegardes et pg_rewind. |
Mot de passe de réplication (replication_password) | password | généré | - | non | oui | non | Mot de passe du rôle replicator avec lequel les réplicas reçoivent les WAL. (ha) |
Mot de passe de l'API REST (restapi_password) | password | généré | - | non | oui | non | Mot de passe d'authentification basique (utilisateur navin) des points sensibles de l'API REST de Patroni (bascule, redémarrage, réinitialisation). (ha) |
TLS (tls_enabled) | bool | false | - | non | non | non | Servir le SQL, la réplication et l'API REST de Patroni en TLS avec le certificat de l'autorité de la console et refuser toute connexion sans TLS (hostnossl reject). Méthodes podman et package seulement : le PostgreSQL de la méthode python est compilé sans OpenSSL. Obligatoire en mode ha quand etcd utilise TLS (certificat client). |
Réseau autorisé (allowed_cidr) | string | 0.0.0.0/0 | - | non | non | non | CIDR autorisé à se connecter avec un mot de passe (scram-sha-256). |
Extensions
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
pgvector (pgvector) | bool | true | - | non | non | non | Créer l'extension vector dans template1 et dans la base de chaque consommateur au provisionnement (type vector, index HNSW et IVFFlat). |
Haute disponibilité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|
Limite de WAL d'un slot (max_slot_wal_keep_size_mb) | int | 10240 | min 1024, max 1048576, MB | non | non | non | WAL maximal qu'un slot de réplication d'un membre arrêté retient (max_slot_wal_keep_size), pour qu'un réplica perdu ne remplisse jamais le disque du leader ; au delà le membre est réinitialisé. (ha) |
Réplication synchrone (synchronous_mode) | bool | false | - | non | non | non | synchronous_mode de Patroni : une validation attend un réplica synchrone et seul ce réplica peut être promu (aucune transaction validée perdue à la bascule, latence de validation plus élevée). (ha) |
Durée de vie de la clé du leader (ttl) | int | 30 | min 10, max 300, s | non | non | non | Durée de vie de la clé du leader dans etcd : un leader qui ne peut pas la renouveler pendant cette durée est rétrogradé et un réplica est promu. (avancé; ha) |
Intervalle de la boucle (loop_wait) | int | 10 | min 1, max 60, s | non | non | non | Secondes entre deux tours de la boucle de haute disponibilité de Patroni. (avancé; ha) |
Délai de nouvelle tentative (retry_timeout) | int | 10 | min 1, max 120, s | non | non | non | Délai des opérations etcd et PostgreSQL que Patroni retente avant une rétrogradation. (avancé; ha) |
Retard maximal à la bascule (maximum_lag_on_failover_mb) | int | 1 | min 0, max 102400, MB | non | non | non | Un réplica plus en retard que cette valeur sur le leader n'est jamais promu (maximum_lag_on_failover). (avancé; ha) |
Dépendances
Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).
| Liaison | Fournie par | Type de connexion | Point d'accès | Facultative | Quand rien n'est lié | Description |
|---|
dcs (ha) | etcd | - | client | non | etcd est ajouté à l'installation | Cluster etcd où Patroni conserve la clé du leader, la liste des membres et la configuration dynamique (mode ha). |
Points d'accès
| Point d'accès | Schéma | Composant | Port | Chemin | Paramètre TLS | Paramètres de liaison | Secrets de liaison | Commande de provisionnement |
|---|
sql | postgresql | postgres | 5432 (port) | - | tls_enabled | database, username, sslmode | password | provision_consumer |
Fichiers de configuration client
Fichiers rendus pour le téléchargement de la configuration client :
postgresql.env (client.env.j2)
Commandes
| Commande | Composant | Cible | Description |
|---|
Provisionner la base d'un consommateur (provision_consumer) | postgres | premier hôte | Crée ou met à jour le rôle et la base d'un service consommateur sur le leader, avec l'extension vector quand pgvector est actif (idempotent). |
Activer une extension (enable_extension) | postgres | premier hôte | Crée une extension dans une base sur le leader (idempotent). La méthode python ne fournit que vector. |
Lister les bases (list_databases) | postgres | premier hôte | Liste les bases de données et leurs propriétaires. |
Afficher l'activité (activity) | postgres | premier hôte | Affiche les sessions de pg_stat_activity du leader. |
État du cluster (cluster_status) | postgres | premier hôte | Mode ha : membres, rôle, état, timeline et retard (patronictl list). Serveur unique : rôle et réplication du serveur. |
Bascule planifiée (switchover) | postgres | premier hôte | Mode ha : déplace le rôle de leader vers le membre indiqué, qui doit être un réplica en flux sain (patronictl switchover) ; les sessions de l'ancien leader sont coupées. (demande une confirmation) |
Réinitialiser un membre (reinit_member) | postgres | premier hôte | Mode ha : supprime le répertoire de données d'un réplica et le clone de nouveau depuis le leader (patronictl reinit). Jamais le leader. (demande une confirmation) |
Appliquer les réglages (push_settings) | postgres | premier hôte | Mode ha : écrit max_connections, wal_keep_size, la limite de WAL des slots, synchronous_mode, ttl, loop_wait, retry_timeout et maximum_lag_on_failover dans la configuration dynamique dans etcd (patronictl edit-config), puis redémarre un par un les membres qui attendent un redémarrage. (demande une confirmation) |
Paramètres des commandes
| Commande | Paramètre | Type | Défaut | Obligatoire | Description |
|---|
provision_consumer | Base de données (database) | string | - | oui | Base de données du consommateur. |
provision_consumer | Rôle (username) | string | - | oui | Rôle de connexion du consommateur. |
provision_consumer | Mot de passe (password) | password | - | oui | Mot de passe du rôle (dérivé par consommateur). |
enable_extension | Base de données (database) | string | - | oui | Base de données où l'extension est créée. |
enable_extension | Extension (extension) | enum | vector | oui | vector (pgvector) ou une extension contrib de PostgreSQL 16. |
switchover | Nouveau leader (candidate) | string | - | oui | Nom du membre du nouveau leader (nom d'hôte, voir l'état du cluster). |
reinit_member | Membre (member) | string | - | oui | Nom du membre du réplica (nom d'hôte, voir l'état du cluster). |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|
postgres | TCP {{ host.ip or '127.0.0.1' }}:{{ config.port }} | 90 tentatives ; intervalle 2 s ; délai 3 s |
Disponibilité (contrôle du service)
| Contrôle | Détails |
|---|
{{ paths.etc }}/check.sh | 30 tentatives ; intervalle 4 s ; délai 30 s |
Test fonctionnel
Crée une table temporaire sur le leader, écrit puis relit une ligne ; avec pgvector, une colonne vector(3) et une requête du plus proche voisin. (postgres: write_read, nearest_neighbour)
Contrôles préalables
| Contrôle | Type | Signification | Sévérité | Composants |
|---|
memory | memory_mb {"min": 1024} | au moins 1024 Mo de mémoire | bloquant | tous les composants |
disk | disk_free_mb {"path": "/var/lib/navin", "min": 5120} | au moins 5120 Mo libres pour /var/lib/navin | avertissement | tous les composants |
sql_port_free | port_free {"param": "port"} | port 5432 libre sur l'hôte | bloquant | tous les composants |
time_sync | time_sync {} | une horloge synchronisée | avertissement | tous les composants |
Sauvegarde et restauration
Sauvegarde physique de tout le serveur prise sur le leader (pg_basebackup, format tar, WAL en flux, manifeste SHA256) ; l'étape de vérification l'extrait et lance pg_verifybackup. Restauration : le répertoire de données du membre de la sauvegarde est remplacé ; en mode ha l'état du cluster dans etcd est réinitialisé, ce membre redémarre comme leader et chaque autre membre est de nouveau cloné depuis lui à son démarrage.
| |
|---|
| Format | pg-basebackup |
| Composant | postgres |
| Fichiers | {{ backup.dir }}/base.tar.gz, {{ backup.dir }}/pg_wal.tar.gz, {{ backup.dir }}/backup_manifest |
| Test de restauration | oui |
| Instances arrêtées pendant la restauration | oui |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Documentation amont