DoiT-Easily

Co-écrit avec Dave Cavaletto

Développer une solution destinée à la vente sur Google Marketplace n'est pas techniquement complexe. Le principal défi tient au fait qu'il s'agit d'une intégration de type entreprise, où vous vous connectez aux systèmes métier d'une autre société, Google, à la différence d'un simple accès à des API publiques comme sur Google Cloud Platform. Google doit valider votre projet GCP avant que vous ne créiez votre intégration, puis valider votre solution une fois celle-ci prête à être publiée.

DoiT-Easily est un projet open-source qui propose un exemple d'intégration entièrement fonctionnel, créé par les ingénieurs de DoiT. L'intégration fonctionne, mais il ne s'agit ni d'un produit prêt pour la production, ni d'un projet supporté. Il s'agit plutôt d'un exemple de démarrage rapide, dont vous pouvez vous inspirer pour apprendre et, éventuellement, l'adapter en solution de production.

Mettez votre produit sur le marché, plus vite !

Dans un précédent article, nous avions donné une vue d'ensemble de la création d'une offre Marketplace. Cet article propose un parcours plus détaillé de DoiT-Easily, en décrivant les éléments architecturaux clés ainsi que les défis que vous rencontrerez en cours de développement. Nous y abordons des fonctionnalités implémentées dans DoiT-Easily qui ne sont pas indispensables à une intégration Marketplace, ainsi que des fonctionnalités présentes dans certaines intégrations Marketplace mais absentes de DoiT-Easily. Pour plus de détails, consultez la documentation et le code dans le projet Github DoiT-Easily, ainsi que la documentation publique Marketplace de Google.

Les schémas suivants détaillent les deux flux principaux : la création d'un nouvel utilisateur et la création d'un nouvel entitlement (achat). Le flux de nouvel entitlement est identique à celui de modification ou d'annulation d'un entitlement. Pour les nouveaux utilisateurs qui souscrivent également à un entitlement, les deux flux se déclenchent en parallèle.

Après les schémas de flux, vous trouverez un schéma et une présentation des composants.

Flux de nouvel utilisateur

Flux d'entitlement

Sur le schéma d'architecture ci-dessous, issu de DoiT-Easily, on retrouve les composants de votre intégration et les API Google avec lesquelles elle s'interface.

Vos composants fonctionnels figurent dans la moitié inférieure du schéma, tandis que les API de Google occupent la moitié supérieure.

Votre SaaS, celui que vous intégrez à Google, n'apparaît pas dans cet exemple. Vos serveurs SaaS peuvent être déployés dans un autre projet Google ou dans le même que le système d'intégration.

Nous détaillons ces composants ci-dessous.

Architecture de DoiT-Easily

Frontend

L'intégration frontend du schéma est une application web, comprenant un client et un serveur. DoiT-Easily implémente un client HTML/AJAX avec des templates HTML. Le serveur est en Python et déployé sur Cloud Run. Vous pouvez bien sûr retenir d'autres technologies dans votre propre implémentation.

Le client front-end affiche la page d'accueil vers laquelle les abonnés sont redirigés pendant le flux d'inscription, après transfert par GCP Marketplace. Le front-end vérifie le JWT de la requête pour authentifier qu'elle provient bien de Google. Une fois l'utilisateur inscrit, le serveur front-end notifie l'API Procurement de Google, créant ainsi le compte Procurement de l'abonné. L'intégralité de la logique serveur du Frontend Integration tient dans la fonction login(), accessible via le chemin /activate ou /login.

Backend

L'intégration backend est un serveur lui aussi déployé sur Cloud Run. Dans DoiT-Easily, c'est le même service Cloud Run, mais vous pourrez décider de créer des services front-end et back-end distincts dans votre application. Le backend reçoit des messages Pub/Sub de Google qui notifient les événements liés aux Entitlements. ("Entitlement" est le terme employé par Google pour désigner un abonnement à votre offre.)

Notez que le fichier api.py, au cœur de l'application Cloud Run, comporte de nombreux endpoints web rarement utilisés ; concentrez-vous donc sur les flux principaux. Le flux principal se déclenche via Pub/Sub par une push-subscription gérée par la fonction handle_subscription_message(), accessible via le chemin /v1/notification.

Backend-UI

DoiT-Easily propose une interface utilisateur supplémentaire pour le backend, qui n'est pas requise par l'architecture d'intégration Marketplace de base. Elle permet de lister les Entitlements en attente et de les approuver manuellement, si votre système n'est pas conçu pour les valider automatiquement. Le code serveur est consultable via le chemin /app dans app.py et il est sécurisé par Identity-Aware Proxy (IAP).

Dans app.py, vous verrez plusieurs endpoints qui prennent en charge cette application, notamment la page principale, ainsi que des méthodes pour lister, approuver ou rejeter les entitlements et lister les comptes.

Autres endpoints

Tous les autres endpoints du fichier api.py peuvent servir de proxy authentifié vers l'API Procurement, afin qu'une solution sur mesure puisse interagir avec DoiT-Easily plutôt qu'avec l'API Procurement directement.

Usage Reporter

Le Usage Reporter, qui ne fait pas partie de DoiT-Easily, remonte l'usage que fait le client de votre produit à l'API Service Control de Google. Il est nécessaire si la facturation s'appuie sur les ressources, comme le volume de données traitées, le nombre d'appels à votre solution, etc. En revanche, si vous proposez une solution gratuite ou facturée par abonnement mensuel, ce composant n'est pas utile : c'est pour cela que DoiT-Easily ne l'inclut pas.

Si vous implémentez un Usage Reporter, vous voudrez sans doute mettre en place votre propre datastore pour suivre les entitlements (les abonnés à votre offre) et exploiter ces enregistrements pour piloter le reporting d'usage vers Google. En l'état, DoiT-Easily n'implémente pas de datastore et s'appuie sur l'API Procurement pour stocker tous les Entitlements et leur état associé.

ISV Provision Service

Si chaque nouveau client impose de nouveaux besoins en ressources à votre solution SaaS, vous pouvez créer ce composant pour les gérer. Par exemple, si chaque client obtient son propre pod ou namespace dans Google Kubernetes Engine, l'ISV Provision Service s'en chargera. Ce service n'étant pas indispensable à la plupart des solutions SaaS, DoiT-Easily ne l'inclut pas.

Autres composants cloud

Outre les composants client et serveur du schéma, DoiT-Easily inclut les ressources d'infrastructure cloud suivantes. Les modules Terraform de DoiT-Easily les déploient pour vous, sauf indication contraire ci-dessous.

Spécifié par Google Marketplace

• IAM : cela inclut les permissions sur votre projet pour plusieurs comptes de service Google. Les permissions de votre compte de service pour accéder à Google ne sont pas définies à cette étape, mais demandées via le Producer Portal (voir l'étape 5 de Set up, documentée ici).
• Pub/Sub : un topic sur lequel Google vous envoie les messages liés aux événements d'entitlement. Le topic se trouve dans un projet appartenant à Google et il est créé par Google lors de l'étape Set up décrite ci-dessous. Votre backend s'y abonne.

Autres services cloud

DoiT-Easily s'appuie sur les technologies cloud suivantes ; vous pouvez en choisir d'autres, du moment qu'elles offrent les mêmes fonctionnalités.

• Des services Cloud Run pour le front-end et le back-end, comme indiqué plus haut.
• Cloud DNS Zone : chaque listing Marketplace possède sa propre adresse publique, vers laquelle Google Marketplace transfère les demandes d'inscription. La DNS Zone sert ces domaines. Le Terraform ne crée pas cette ressource ; nous partons du principe que vous disposez déjà d'une zone existante.
• Un Load Balancer reçoit les requêtes, y compris celles transférées depuis Google Marketplace, et les achemine vers le service correspondant au listing Marketplace concerné. Le Load Balancer est associé à une adresse IP publique, à un certificat TLS, à IAP et à des règles de routage.
• Un fichier de configuration pour Cloud Run, stocké comme Secret dans GCP Secret Manager. Le Terraform crée l'objet Secret. Lors du déploiement de DoiT-Easily, pensez à mettre à jour la valeur dans Secret Manager si nécessaire. Cela incrémente le numéro de version, qui doit être reporté dans le fichier tfvars. La configuration contient des valeurs d'environnement à garder secrètes et, par commodité, d'autres qui ne le sont pas.

La mise en place de DoiT-Easily comporte les phases suivantes. Plusieurs d'entre elles disposent de modules Terraform. Copiez le fichier example.tfvars en terraform.tfvars et modifiez les valeurs, puis exécutez terraform init et terraform apply.

Pré-requis

La phase de pré-requis porte ce nom car elle précède la validation de votre projet par Google. Le Terraform crée le projet lui-même ainsi que les rôles IAM des comptes de service Google sur votre projet, et un rôle pour l'utilisateur qui exécute le déploiement.

Configuration avec Google

Vous configurez votre projet Google en soumettant un formulaire de demande d'approbation, ce qui peut prendre plusieurs semaines. (N'hésitez pas à demander l'aide de DoiT pour vous y orienter !) Une fois l'approbation obtenue, vous définissez intégralement votre listing dans le Producer Portal, en précisant la tarification, les informations produit et le compte de service auquel Google accordera des permissions.

Déploiement

Vous compilez l'application Cloud Run avec Cloud Build, en poussant l'image vers Artifact Registry. Vous la déployez ensuite avec Terraform, ainsi que les ressources cloud nécessaires, comme la DNS Zone et le Load Balancer.

Tests

Pendant le développement, vous pouvez exécuter DoiT-Easily en local et lancer les tests unitaires fournis.

Une fois la solution déployée, vous pouvez la tester manuellement, en parcourant l'inscription utilisateur, l'achat et les approbations dans votre projet Marketplace. (Tant que le listing n'est pas publié, il reste en mode private preview.)

Un framework de tests d'intégration automatisés fourni par Google est également disponible ; Google exige qu'il soit validé avant publication.

Si vous ne proposez que des private offers, les tests automatisés n'aboutiront jamais. Vous pouvez sauter cette étape et publier malgré tout votre listing.

Pour la dernière étape, la publication, vous demandez une approbation manuelle à Google. Vous ne pouvez donc pas livrer des correctifs et des améliorations en continu, plusieurs fois par jour, comme dans une logique de déploiement continu. Chaque nouvelle version peut entraîner un aller-retour de plusieurs jours dans l'attente de l'approbation.

Toute implémentation d'une intégration Marketplace, y compris DoiT-Easily, présente certaines limitations essentielles, par contraste avec les applications cloud classiques. Certaines fonctionnalités envisageables ne sont d'ailleurs pas implémentées dans DoiT-Easily.

Approbation requise par projet

Une fois les pré-requis en place, Google doit approuver votre projet. Vous ne disposerez donc que d'un seul projet sur lequel votre solution pourra fonctionner ; pas de projets séparés pour le développement, les tests, la pré-production et la production.

Les ressources qui doivent être approuvées avant que votre projet soit utilisable ne peuvent pas être supprimées et recréées facilement. Impossible donc de réaliser un test de bout en bout dans lequel un script crée un nouveau projet bac à sable, configure l'application, exécute les tests, puis supprime l'ensemble. De même, impossible de nettoyer toutes les ressources de votre projet Marketplace pour repartir de zéro. Vous pouvez exécuter un test à l'aide des fonctionnalités de test et de prévisualisation intégrées à Marketplace, mais il ne commencera ni ne se terminera sur un environnement vierge.

Mettre en place des environnements de développement séparés pour chaque membre de l'équipe n'est pas non plus possible. Vous pouvez en revanche partager un projet entre les membres de l'équipe. Il vous faudra alors concevoir une architecture dans laquelle ils créent des listings distincts ; ils partageront toute le reste de l'infrastructure : le projet, les paramètres IAM, le Load Balancer, le topic Pub/Sub et la DNS zone. Chaque application devra s'abonner au topic Pub/Sub et ne traiter que les messages qui la concernent. DoiT-Easily n'a pas pleinement implémenté la prise en charge de listings multiples : il ne vous empêche pas d'en créer plusieurs, mais le code de déploiement Terraform n'est pas conçu pour cela.

Cela signifie aussi que pour exécuter DoiT-Easily, comme toute autre intégration Marketplace, il vous faudra un projet Marketplace officiel qui passera par l'approbation de Google.

Scénarios alternatifs

DoiT-Easily a été conçu pour illustrer un scénario, mais comme souvent avec les intégrations business-to-business de type entreprise, les solutions Marketplace se déclinent fréquemment en variantes sur mesure. Citons par exemple une solution réservée aux private offers : elle donne aux éditeurs un meilleur contrôle sur leur processus commercial et évite d'avoir à mettre en place un front-end tel que décrit plus haut. En contrepartie, cela impose un outil interne pour gérer les private offers, et de nombreux éditeurs développent à cette fin une application web interne.