Sauvegarde et restauration ClickHouse
Fonctionnement de la sauvegarde ClickHouse
Un sidecar de sauvegarde s'exécute aux côtés de ClickHouse, surveillant en continu les changements et prenant automatiquement des sauvegardes complètes et incrémentielles planifiées : il n'y a aucune tâche cron distincte à configurer.
Les sauvegardes sont :
- Cohérentes au niveau applicatif : prises via le mécanisme natif
FREEZEde ClickHouse (liens physiques zéro-copie), et non via un instantané de volume brut, de sorte qu'une sauvegarde ne capture jamais une table en cours d'écriture. - Écrites dans votre object storage : les métadonnées/manifestes ainsi que les blobs de données sous-jacents sont copiés dans votre bucket configuré, sous le préfixe de chemin que vous configurez ci-dessous.
- Dédupliquées et conscientes des chaînes : les sauvegardes incrémentielles ne stockent que ce qui a changé ; les politiques de rétention suppriment des chaînes de sauvegarde entières plutôt que de laisser des incréments orphelins.
FREEZE fonctionne en créant des liens physiques vers les données de table en direct, et non des copies. Les permissions, la propriété et les attributs d'un lien physique sont une propriété des données sous-jacentes elles-mêmes : ils sont partagés entre tous les liens physiques qui pointent vers elles. Modifier les permissions sur un fichier sous le chemin de sauvegarde les modifie aussi sur les données en direct que ClickHouse lit et écrit activement, ce qui peut entraîner une corruption des données. Ne touchez jamais manuellement aux permissions à cet endroit ; laissez ClickHouse et le sidecar de sauvegarde gérer ce chemin exclusivement.
Configuration du sidecar de sauvegarde
Un sidecar de sauvegarde est configuré par défaut sur le pod ClickHouse, conditionné par clickhouse.backup.enabled (true par défaut). Il exécute clickhouse-backup en mode server --watch, qui auto-planifie des sauvegardes complètes et incrémentielles en interne ; il n'y a aucune tâche cron distincte, ni rien d'autre à déployer. Ne définissez clickhouse.backup.enabled: false que si vous avez l'intention de gérer entièrement le sidecar vous-même via clickhouse.sidecars.
Destination de l'object storage
La destination de sauvegarde n'a aucune valeur par défaut : vous devez la configurer avant que les sauvegardes puissent s'exécuter. Elle est déclarée sous clickhouse.backup.objectStorage, avec la même structure et le même vocabulaire que le bucket de données propre à ClickHouse sous clickhouse.objectStorage (voir Backends de stockage objet) : un provider plus un bloc de provider portant le bucket/conteneur, un prefix facultatif, et soit credentialless: true (identité de charge de travail, aucune clé statique), soit une référence existingSecret. Les identifiants ne vivent jamais que dans un secret Kubernetes que vous créez séparément, jamais en ligne dans votre fichier de values (le même modèle que celui décrit dans Prérequis) ; le chart refuse les clés d'identifiants dans extraVars.
Le chart dérive les deux chemins de stockage à partir de l'unique prefix : les manifestes de sauvegarde se retrouvent sous <prefix>/metadata et les copies des blobs de données du disque objet sous <prefix>/objects.
Seule la structure est partagée avec le bucket de données, jamais les valeurs : utilisez un bucket réellement distinct (voir Exigences de bucket). Le chart l'impose et fait échouer le déploiement si la sauvegarde cible le bucket ou le conteneur contenant les données qu'elle protège. Choisissez votre provider ci-dessous.
- AWS S3
- Azure Blob Storage
- GCS
- IBM Cloud Object Storage
- MinIO
clickhouse:
backup:
objectStorage:
provider: s3
s3:
bucket: '<bucket-name>'
region: '<region>'
prefix: 'backups'
credentialless: true
Bucket cible : s3.bucket. Aucune entrée d'identifiant n'est nécessaire avec credentialless: true : avec IRSA (voir Backends de stockage objet), le token du ServiceAccount est automatiquement monté dans chaque conteneur du pod, y compris ce sidecar. Avec des clés statiques à la place, définissez credentialless: false et faites pointer existingSecret vers un secret portant les clés access-key-id et secret-access-key (la même forme que le secret du bucket de données, avec ses propres identifiants distincts).
Avec Microsoft Entra Workload ID configuré pour le disque de stockage (voir Backends de stockage objet), le sidecar en hérite gratuitement : le webhook de mutation AKS injecte les variables d'environnement du token fédéré et le volume de token projeté dans chaque conteneur du pod par défaut, pas seulement dans celui de ClickHouse : aucune configuration distincte n'est nécessaire. Ajoutez simplement :
clickhouse:
backup:
objectStorage:
provider: azblob
azblob:
storageAccountName: '<storage-account-name>'
containerName: '<container-name>'
prefix: 'backups'
credentialless: true
Bucket cible : azblob.storageAccountName + azblob.containerName (le compte est passé par son nom ici, contrairement au storageAccountUrl du bucket de données : le sidecar et le disque ClickHouse le prennent sous des formes différentes). Aucune entrée d'identifiant n'est nécessaire avec credentialless: true. Assurez-vous que le rôle RBAC accordé à l'identité managée (voir Backends de stockage objet) couvre aussi le conteneur de sauvegarde, s'il est différent de celui de ClickHouse. Avec une clé de compte statique à la place, définissez credentialless: false et faites pointer existingSecret vers un secret portant une clé account-key (un secret ayant la forme de celui du bucket de données, avec sa clé supplémentaire account-name, fonctionne tel quel : seule account-key est lue).
clickhouse:
backup:
objectStorage:
provider: gcs
gcs:
bucket: '<bucket-name>'
prefix: 'backups'
existingSecret: 'clickhouse-backup-gcs-credentials'
Le client GCS du sidecar de sauvegarde n'accepte pas les clés HMAC (contrairement au disque propre de ClickHouse, voir Backends de stockage objet) : il lui faut sa propre clé JSON native de compte de service, passée en tant que secret Kubernetes plutôt que définie en ligne dans les values, le même modèle que celui décrit dans Prérequis : créez-la directement, ou synchronisez-la depuis votre propre magasin de secrets via un SecretStore/ExternalSecret de l'External Secrets Operator ou un Vault Secrets Operator.
Quelle que soit la façon dont vous le peuplez, le secret (n'importe quel nom, référencé par existingSecret) doit contenir une clé credentials-json avec le contenu du fichier de clé JSON. Si vous le créez directement :
kubectl create secret generic clickhouse-backup-gcs-credentials \
--namespace <namespace> \
--from-file=credentials-json=<path-to-service-account-key.json>
Bucket cible : gcs.bucket. Nécessite l'identifiant ci-dessus.
Le client GCS de clickhouse-backup utilise l'API native de GCS et sa chaîne d'Application Default Credentials, de sorte que gcs.credentialless: true peut s'authentifier via GKE Workload Identity Federation, sans clé JSON.
Ce chemin provient de la documentation propre à clickhouse-backup (son client GCS prend en charge les identifiants par défaut) et de la documentation Workload Identity Federation de GCP, mais n'a pas été testé de bout en bout sur un véritable cluster GKE. Validez-le vous-même avant de vous y fier en production.
Cela nécessite une configuration Workload Identity Federation spécifique au sidecar de sauvegarde (distincte du disque propre de ClickHouse, qui nécessite toujours la paire de clés HMAC statiques quoi qu'il arrive) :
- Workload Identity Federation activé sur votre cluster GKE.
- Un ServiceAccount Kubernetes dédié, annoté avec l'e-mail d'un compte de service GCP.
- Une liaison de politique IAM autorisant ce ServiceAccount à usurper l'identité du compte de service GCP.
- Un rôle de stockage accordé au compte de service GCP, limité au bucket.
Activer Workload Identity Federation (s'il n'est pas déjà activé sur le cluster) :
gcloud container clusters update <cluster-name> \
--zone <zone> \
--workload-pool=<project-id>.svc.id.goog
Créer le compte de service GCP :
gcloud iam service-accounts create clickhouse-backup --project=<project-id>
Configuration du chart : annotez le ServiceAccount ClickHouse pour qu'il puisse usurper l'identité du compte de service GCP :
clickhouse:
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: clickhouse-backup@<project-id>.iam.gserviceaccount.com
Liaison de politique IAM : autorisez le ServiceAccount Kubernetes à usurper l'identité du compte de service GCP (remplacez <namespace>) :
gcloud iam service-accounts add-iam-policy-binding \
clickhouse-backup@<project-id>.iam.gserviceaccount.com \
--role roles/iam.workloadIdentityUser \
--member "serviceAccount:<project-id>.svc.id.goog[<namespace>/clickhouse]"
Rôle de stockage : accordez au compte de service GCP l'accès au bucket :
gcloud storage buckets add-iam-policy-binding gs://<bucket-name> \
--member=serviceAccount:clickhouse-backup@<project-id>.iam.gserviceaccount.com \
--role=roles/storage.objectAdmin
Une fois cela en place :
clickhouse:
backup:
objectStorage:
provider: gcs
gcs:
bucket: '<bucket-name>'
prefix: 'backups'
credentialless: true
Bucket cible : gcs.bucket. Aucune clé JSON à créer ou stocker. Pour usurper explicitement l'identité d'un compte de service GCP spécifique au lieu de vous fier à la chaîne d'Application Default Credentials, ajoutez GCS_SA_EMAIL: '<gcp-sa-email>' sous clickhouse.backup.config.extraVars.
clickhouse-backup atteint IBM Cloud Object Storage via son type de stockage distant s3, sur le point de terminaison direct COS avec adressage de style chemin et une paire de clés HMAC statiques :
clickhouse:
backup:
objectStorage:
provider: s3
s3:
endpoint: 'https://s3.direct.<region>.cloud-object-storage.appdomain.cloud'
bucket: '<backup-bucket-name>'
region: '<region>-standard' # the bucket's storage class code, for example eu-de-standard
prefix: 'backups'
forcePathStyle: true # required whenever a custom endpoint is set
existingSecret: 'clickhouse-backup-cos-credentials'
Les identifiants sont passés en tant que secret Kubernetes, jamais en ligne dans votre fichier de values (le même modèle que celui décrit dans Prérequis). Quelle que soit la façon dont vous le peuplez, le secret (n'importe quel nom, référencé par existingSecret) doit contenir les clés access-key-id et secret-access-key :
kubectl create secret generic clickhouse-backup-cos-credentials \
--namespace <namespace> \
--from-literal=access-key-id=<cos-hmac-access-key-id> \
--from-literal=secret-access-key=<cos-hmac-secret-access-key>
Bucket cible : s3.bucket, un bucket dédié aux sauvegardes, créé au préalable avec un identifiant de service HMAC à portée Writer comme le bucket de données. Nécessite l'identifiant ci-dessus.
clickhouse-backup dialogue avec MinIO via son type de stockage distant s3 également (comme AWS S3), simplement pointé vers votre point de terminaison MinIO avec adressage de style chemin et une paire clé d'accès/clé secrète statique, puisque MinIO n'a pas d'identité équivalente à IAM avec laquelle se fédérer :
clickhouse:
backup:
objectStorage:
provider: s3
s3:
endpoint: 'http://<minio-host>:<minio-port>'
bucket: '<bucket-name>'
region: 'us-east-1' # required by the S3 client even though MinIO ignores it
prefix: 'backups'
forcePathStyle: true # required whenever a custom endpoint is set
existingSecret: 'clickhouse-backup-minio-credentials'
config:
extraVars:
S3_DISABLE_SSL: 'true' # omit and use an https:// endpoint above instead if MinIO terminates TLS
Les identifiants sont passés en tant que secret Kubernetes, jamais en ligne dans votre fichier de values (le même modèle que celui décrit dans Prérequis). Quelle que soit la façon dont vous le peuplez, le secret (n'importe quel nom, référencé par existingSecret) doit contenir les clés access-key-id et secret-access-key :
kubectl create secret generic clickhouse-backup-minio-credentials \
--namespace <namespace> \
--from-literal=access-key-id=<minio-access-key> \
--from-literal=secret-access-key=<minio-secret-key>
Bucket cible : s3.bucket. Nécessite l'identifiant ci-dessus.
Politiques de cycle de vie des buckets
Les règles de cycle de vie et les protections de bucket pour les deux buckets sont documentées ensemble dans Politiques de cycle de vie des buckets : voir la sous-section Backup bucket pour celui-ci (versionnage, Object Lock, réplication, mises en garde sur le niveau d'archivage) et la sous-section ClickHouse data bucket pour le bucket de données propre à ClickHouse. Les deux nécessitent des règles différentes, par endroits opposées.
Paramètres ajustables
D'autres paramètres du sidecar disposent d'un champ typé sous clickhouse.backup.config. Ne surchargez que ceux dont vous avez besoin :
clickhouse:
backup:
config:
backupsToKeepRemote: 30 # only overriding retention here
| Paramètre | Objectif | Par défaut |
|---|---|---|
watchSchedules | Planning de sauvegarde complète/incrémentielle piloté par cron, voir Comprendre le planning de sauvegarde ci-dessous. | name=ch-bkp,full=0 2 * * 0,increment=0 2 * * *,full_type=rebase,delete_previous_cycle=false |
backupsToKeepRemote | Nombre de sauvegardes individuelles à conserver dans l'object storage : chaque sauvegarde complète et chaque incrément compte séparément, voir Comprendre le planning de sauvegarde ci-dessous. | 7 |
rebaseBeforeRemoveOldRemote | Sans cela, backupsToKeepRemote n'est pas un plafond strict : avec des chaînes incrémentielles, clickhouse-backup ne supprimera pas une chaîne dont un incrément plus récent dépend encore, de sorte que le nombre conservé peut dépasser la limite. Cela rebase le plus ancien incrément encore dans la fenêtre de rétention sur une sauvegarde complète autonome, le rendant indépendant de la chaîne plus ancienne qui le précède, laquelle peut alors être supprimée, maintenant une rétention stricte. | true |
uploadConcurrency | Tables téléversées en parallèle pendant une sauvegarde, et (même valeur) fichiers par table téléversés en parallèle. | 2 |
downloadConcurrency | Identique à uploadConcurrency, pour la restauration. | 2 |
s3Concurrency | Morceaux parallèles pour le transfert multipart S3 d'un seul fichier, un niveau plus fin que uploadConcurrency/downloadConcurrency. | 2 |
rebaseConcurrency | Tables traitées en parallèle pendant une opération rebase (voir full_type=rebase ci-dessous). | 2 |
logLevel | Verbosité des logs du sidecar. | info |
allowEmptyBackups | Sans cela, une nouvelle installation sans table encore présente est traitée comme une erreur fatale, mettant le sidecar en crash-loop. | true |
Les paramètres de concurrence utilisent par défaut une valeur fixe et prudente plutôt que l'auto-détection propre à clickhouse-backup, qui se dimensionne sur le nombre total de CPU du nœud plutôt que sur la limite CPU réelle de ce conteneur : augmentez-les si vous avez donné plus de CPU au sidecar et souhaitez des sauvegardes et restaurations plus rapides.
Tout autre paramètre non sensible de clickhouse-backup va sous clickhouse.backup.config.extraVars, sous son nom natif en SCREAMING_CASE ; voir la référence de configuration propre à clickhouse-backup pour la liste exhaustive. Le chart rejette une clé extraVars qui entre en collision avec un champ typé ci-dessus (par exemple extraVars.BACKUPS_TO_KEEP_REMOTE) ou avec un champ appartenant à clickhouse.backup.objectStorage (par exemple extraVars.S3_BUCKET) : définissez plutôt le champ dédié. Il rejette aussi purement et simplement les clés d'identifiants (S3_ACCESS_KEY, GCS_CREDENTIALS_JSON, AZBLOB_ACCOUNT_KEY, ...) : extraVars est rendu dans un ConfigMap, pas un secret, de sorte que les identifiants ne passent jamais que par existingSecret (ou votre propre secret via clickhouse.backup.sidecar.extraEnvVarsSecret).
Comprendre le planning de sauvegarde
WATCH_SCHEDULES pilote la cadence de sauvegarde avec des expressions cron. Un planning a la forme :
name=<name>,full=<cron>[,increment=<cron>][,full_type=create|rebase][,delete_previous_cycle=true|false]
| Clé | Requis | Signification |
|---|---|---|
name | Oui | Préfixe pour les noms de sauvegarde de cette chaîne. Vous permet d'exécuter plusieurs plannings indépendants côte à côte, séparés par ;. |
full | Oui | Expression cron pour la sauvegarde complète. |
increment | Non | Expression cron pour la sauvegarde incrémentielle. Omettez-la pour des sauvegardes complètes uniquement. |
full_type | Non (create) | create re-téléverse toutes les données pour chaque sauvegarde complète. rebase effectue à la place une copie côté serveur de la chaîne précédente (pas de re-téléversement, bien plus rapide), mais seulement une fois qu'une sauvegarde précédente existe déjà ; le tout premier cycle revient toujours à create. |
delete_previous_cycle | Non (false) | true supprime toutes les sauvegardes plus anciennes de cette chaîne dès qu'une nouvelle sauvegarde complète réussit, ne conservant que le cycle actuel. false laisse les cycles plus anciens en place, élagués uniquement par backupsToKeepRemote ci-dessus. |
Les expressions cron acceptent la syntaxe standard à 5 champs (minute, heure, jour, mois, jour de la semaine), un champ de secondes initial facultatif, et des descripteurs de style @every/@daily.
Valeur par défaut du chart :
clickhouse:
backup:
config:
watchSchedules: name=ch-bkp,full=0 2 * * 0,increment=0 2 * * *,full_type=rebase,delete_previous_cycle=false
Ceci exécute une sauvegarde complète chaque dimanche à 2h du matin (via rebase une fois qu'une précédente existe, donc sans re-téléversement) et une sauvegarde incrémentielle chaque jour à 2h du matin. Le dimanche, les expressions cron full et increment se déclenchent au même instant : la sauvegarde complète a toujours la priorité, de sorte qu'aucun incrément distinct ne s'exécute ce jour-là.
Fenêtre de rétention : avec delete_previous_cycle: false, backupsToKeepRemote conserve les N sauvegardes les plus récentes, en comptant chaque sauvegarde complète et chaque incrément comme sa propre entrée. À 7 entrées par semaine (1 complète + 6 incréments), backupsToKeepRemote: 7 conserve environ 1 semaine d'historique.
Fraîcheur des sauvegardes
La fraîcheur des sauvegardes est exposée à l'intérieur du produit à l'aide des tables système propres à ClickHouse. Considérez une sauvegarde comme défaillante si aucune sauvegarde complète valide n'existe dans votre objectif de point de reprise, ou si aucune nouvelle sauvegarde n'a été prise récemment.
La boucle de surveillance du sidecar réessaie une sauvegarde échouée au prochain instant planifié au lieu de s'arrêter : un échec persistant (mauvais identifiants, bucket inaccessible, disque plein) logge une erreur à chaque tentative mais ne fait jamais planter le conteneur. Le statut du pod et le compteur de redémarrages restent au vert tout du long. Voir Supervision et alerting ClickHouse pour mettre en place un signal externe qui, lui, détecte cela.
Restauration
Restaurer les données ClickHouse est une opération manuelle et délibérée : elle n'est pas déclenchée automatiquement. clickhouse-backup restaure sur place, sur la même instance ClickHouse aux côtés de laquelle s'exécute le sidecar : il a besoin d'un accès direct au système de fichiers pour attacher les parties de données de la sauvegarde, la même exigence qui le maintient déployé en tant que sidecar en premier lieu (voir Fonctionnement de la sauvegarde ClickHouse ci-dessus). Il n'existe pas de flux de restauration vers une instance vide distincte sans mettre en place tout un second déploiement ClickHouse.
Procédure de haut niveau :
- Capturez d'abord l'état actuel :
clickhouse-backup create_remotesur la ou les tables concernées, même si ces données sont déjà dégradées. Cela vous donne un repli distinct de votre chaîne de sauvegarde habituelle si la restauration elle-même tourne mal. - Identifiez la sauvegarde à partir de laquelle restaurer : listez les sauvegardes distantes, vérifiez qu'elle n'est pas signalée comme défectueuse, et que sa chaîne de sauvegarde est intacte.
- Vérifiez la compatibilité de version avant de vous engager dans une restauration complète :
clickhouse-backup download --schema <backup_name>ne récupère que le schéma et les métadonnées (léger, sans données de table), ce qui vous permet d'inspecterclickhouse_versiondans lemetadata.jsonrésultant par rapport à la version de ClickHouse actuellement en cours d'exécution. - Arrêtez les écritures vers la ou les tables concernées : mettez en pause ou réduisez l'échelle des producteurs qui y écrivent.
- Restaurez d'abord sous un nom différent (
--restore-database-mapping/--restore-table-mapping), jamais directement dans la table en direct. - Vérifiez la copie restaurée (nombre de lignes, contrôle ponctuel de valeurs connues) avant de toucher à la production.
- Basculez : une fois la copie mappée validée, restaurez à nouveau directement sur le nom de la table en direct avec
--rm(restore/restore_remote --rm <backup_name>) :clickhouse-backupsupprime le schéma existant et le réattache à partir de la sauvegarde.
Pour simplement tester qu'une sauvegarde fonctionne (et non pour répondre à un incident réel), restaurez plutôt sous un nom de table ou de base de données jetable, afin qu'un exercice ne touche jamais aux données de production.
Si vous réessayez une restauration en utilisant le même nom de sauvegarde après une tentative échouée ou interrompue, l'outil de restauration peut reprendre à partir d'un état local obsolète et ne restaurer que le schéma (DDL), en ignorant silencieusement les données réelles, sans erreur. Si une restauration semble vide ou incomplète, effacez l'état local de l'outil avant de réessayer, ou utilisez une cible distincte à chaque fois.
Portée de la reprise après sinistre
Certaines fonctionnalités qui utilisent ClickHouse joignent aussi ces données à des informations stockées dans PostgreSQL (par exemple, un inventaire des machines appartenant à votre organisation). Restaurer ClickHouse seul, dans un environnement dont le PostgreSQL diffère, produit des résultats incohérents dans le produit : les données ClickHouse et le registre PostgreSQL ne concordent pas entre eux.
Une reprise après sinistre complète pour ces fonctionnalités nécessite de restaurer à la fois ClickHouse et PostgreSQL à un point cohérent dans le temps. Planifiez votre stratégie de sauvegarde PostgreSQL (voir Sauvegarde et restauration) et votre stratégie de sauvegarde ClickHouse ensemble, et testez une restauration combinée dans le cadre de vos exercices de reprise après sinistre.
Objectifs de reprise
Nous ne publions pas actuellement d'objectif de point de reprise (RPO) ni d'objectif de temps de reprise (RTO) fixe pour ClickHouse : ceux-ci dépendent de votre cadence de sauvegarde et de votre volume de données. Nous recommandons d'exécuter un exercice de restauration sur votre propre volume de données pour mesurer votre RTO réel, et de régler votre cadence de sauvegarde (fréquence des sauvegardes complètes et incrémentielles) pour correspondre à la fenêtre de perte de données que vous êtes prêt à accepter.