Versionning d’API, Zero Downtime Deployment et migration SQL : théorie et cas pratique

Il est possible de se passer complètement de script de migration au sens traditionnel : vous exposez les services en /v2, et, lorsqu’ils sont appelés pour une donnée encore au format /v1, vous migrez la donnée à la volée. Cela permet de migrer les données petit à petit au fur et à mesure que les utilisateurs des services appelleront les APIs /v2. C’est l’approche qui est souvent prise avec les bases de données NoSQL.

Malheureusement, en procédant ainsi, il est possible que la migration ne se termine jamais, ou alors seulement dans très longtemps (si vous purgez les données trop anciennes). Pendant ce temps, vous devez maintenir le code supplémentaire permettant de prendre en charge ce cas.

L’autre approche est d’utiliser un script. Cela permet de faire en sorte que la migration se fasse rapidement. C’est le même type de script que vous utilisez pour vos migrations habituelles, sauf qu’il doit prendre en compte le fait qu’il s’exécute en même temps que le code. Ainsi toutes les opérations qui créent des verrous pendant plus de quelques millisecondes ne doivent pas être utilisées, et il faut s’assurer de ne pas créer d’interblocage.

La migration doit se faire de manière transactionnelle, pour éviter d’introduire des incohérences dans les données. En cas de problème, le script doit également pouvoir être interrompu et relancé sans que cela ne perturbe l’exécution du programme.

Dans l’article c’est cette approche que nous allons utiliser.

Sans ZDD, le process de migration est classiquement le suivant :

En ZDD, plus question de fermer le service : la migration de données a lieu « à chaud ».

Il y a deux manières possibles de s’y prendre, suivant que la migration a lieu avant ou après l’ouverture des services /v2 :

La première approche permet d’ouvrir les services /v2 plus rapidement car il n’y a pas besoin d’attendre la migration des données.

La seconde approche est plus simple :

Sauf si votre process de migration est extrêmement long, la seconde approche est à privilégier, et c’est celle qui sera utilisée dans la suite de l’article.

Les migrations d’APIs ouvertes posent deux problèmes métier et un problème technique.

Sans ZDD la situation est claire : on arrête l’application, les données sont migrées, et on redémarre l’application dans la nouvelle version. Il y a donc un avant et un après.

Avec ZDD, la migration s’effectue à chaud pendant que les services sont disponibles, s’ajoute une situation intermédiaire.

Pendant cette période, les données peuvent donc être encore stockées au format /v1 ou migrées au format /v2.

Il faut alors parvenir à déterminer dans quel état sont les données : pour savoir quel code doit être appelé il faut savoir si la donnée a été migrée ou pas. De plus, le morceau de code en charge de cela va être exécuté très souvent, il doit donc être très efficace.

En cas de difficulté, la solution qui devrait fonctionner dans tous les cas est d’ajouter dans les tables impliquées un numéro indiquant la « version de schéma » de la donnée correspondante, et qui sera incrémenté lors de la migration de la donnée. Dans ce cas l’opération de vérification est très simple et rapide. L’opération d’ajout de colonne est alors à faire en avance de phase, ce qui augmente le travail nécessaire à la migration.

Si vous choisissez de faire la migration de données après l’ouverture de /v2, s’ajoute le cas où on appelle une api /v2 alors que la donnée est encore stockée au format v1. Il faut alors migrer la donnée à chaud, de manière transactionnelle en limitant les ralentissements induits.

Pour résumer, il y a quatre situations :

Lorsque vous ouvrez /v2 pour la première fois, faites-attention à la manière dont la bascule vers la nouvelle version est faite.

Avant de rendre les nouveaux endpoints accessibles, assurez-vous que tous les serveurs utilisent la dernière version de l’application. Dans le cas contraire, si vous appelez un /v1 alors que la donnée correspondante a été migrée en v2 le code ne saura pas la lire correctement et risque de planter ou de renvoyer une information fausse.

Un autre problème se pose suivant la manière dont vous avez implémenté les modifications de donnée lorsque vous appelez une API /v1.

Le premier cas consiste à sauvegarder la donnée au format v2, mais cela veut dire qu’à nouveau, les versions précédentes de l’application ne pourront pas la lire. La solution la plus simple est alors d’utiliser le feature flipping pour faire basculer le code.

Dans le cas contraire, votre code doit détecter sous quel format la donnée est stockée, et la resauvegarder sous ce même format : une donnée v1 reste en v1, et une donnée v2 reste en v2.
On évite le feature flipping, mais en échange le code est plus complexe.

Pour décomissionner /v1 il suffit de rendre les endpoints inaccessibles, la suppression du code peut se faire plus tard.

Comme on vient de le voir, le ZDD s’appuie beaucoup sur l’utilisation de la base de données, et notamment ses fonctionnalités d’accès concurrent. Si vos comportements métiers sont simples, que vous utilisez un ORM, et que vous avez des tests de performances automatisés, il s’agit d’un domaine auquel vous n’avez pas souvent à vous intéresser. Si vous vous y prenez mal, il est facile de bloquer la base, renvoyer des erreurs (en cas d’interblocage), ou des résultats incohérents.

Notre conseil est de bien vous documenter en amont voire de faire des POC pour éviter d’avoir à refaire un design parce que votre base de données ne fonctionne pas comme vous l’imaginiez. Ne faites pas confiance à des souvenirs ou à des rumeurs : lisez en détail la documentation correspondant à la version de l’outil que vous utilisez, et surtout testez !

Si vous n’avez jamais creusé ces sujets ou que vous êtes rouillé·e, la première migration vous demandera sûrement pas mal de travail, et vous donnera quelques sueurs froides lorsque vous l’exécuterez. Mais dites-vous que toutes les opérations suivantes manipuleront les mêmes concepts, et se passeront donc beaucoup mieux.

REST possède deux caractéristiques qui en font un candidat idéal pour le ZDD :

Si vos services sont exposés d’une autre manière, il faudra donc vous intéresser à ces sujets. Les sessions, comme tous les types de cache, peuvent demander une attention particulière si les données qu’elles contiennent font l’objet d’un changement de structure entre versions.

Dans notre exemple le problème de compatibilité est le suivant : une fois une personne migrée, elle peut avoir plusieurs adresses. Que faire quand on récupère cette même personne en passant par l’API /v1 ?

Ici il n’y a pas de réponse évidente : il n’y a pas de notion d’adresse préférée, ou de dernière adresse utilisée qui fournirait une manière de discriminer les différentes possibilités. Comme la réponse influe sur le comportement de l’API, c’est une décision à prendre par les personnes du métier.

La solution choisie ici est de renvoyer une adresse parmi celle dans la liste. Elle n’est pas parfaite, mais elle peut être acceptable suivant l’usage qui en est fait : il revient aux personnes du métier d’en décider.

Pour résoudre la question de transactionnalité, nous avons choisi la solution la plus simple : poser un verrou sur les entrées correspondantes de la table person.

Si toutes les opérations suivent le même principe, ce verrou joue le rôle d’une mutex en s’assurant que les appels s’exécutent bien l’un après l’autre : lorsqu’une opération pose un risque, elle commence par demander l’accès à ce verrou, et pour cela elle doit attendre son tour.

Exemple avec un appel à PUT /v1/people/127 alors que la personne correspondante est stockée au format v2 mais n’a pas encore d’adresse.

Exemple sans verrou :

Résultat : la personne se retrouve avec deux adresses !

Exemple avec verrou :

Résultat : une seule adresse.

Le script de migration déplace les données par blocs de person à address.

Dans notre exemple, une fois le code basculé à la nouvelle version, toutes les données sont écrites au format v2, qu’il s’agisse des créations ou des modifications.

La migration est donc irréversible, nous savons qu’il suffit de migrer toutes les données une fois pour que le travail soit fait.

En cas d’arrêt du script, les données déjà migrées ne sont pas perdues, et relancer le script ne pose pas de problèmes, les données migrées n’étant pas retraitées.

L’implémentation se trouve sur GitHub. Le code est en open source sous licence MIT, vous pouvez donc vous en servir.

Chaque étape de la migration est dans un module à part, cela permet de facilement examiner ce qui se passe sans avoir à manipuler git.

Le code est en Java et utilise la bibliothèque Dropwizard. La base de donnée est PostgreSQL, l’accès se fait via Hibernate, et les migrations SQL utilisent Liquibase.

Quelques éléments saillants :