DoiT-Easily

Verfasst gemeinsam mit Dave Cavaletto

Eine Lösung für den Vertrieb über den Google Marketplace zu entwickeln, ist technisch kein Hexenwerk. Die eigentliche Herausforderung: Es handelt sich um eine Integration auf Enterprise-Niveau, bei der Sie sich an die Geschäftssysteme eines zweiten Unternehmens – Google – anbinden, statt frei verfügbare APIs wie auf der Google Cloud Platform zu nutzen. Google muss Ihr GCP-Projekt freigeben, bevor Sie die Integration aufsetzen, und anschließend Ihre fertige Lösung freigeben, sobald sie für das Release bereit ist.

DoiT-Easily ist ein Open-Source-Projekt mit einer voll funktionsfähigen Beispielintegration, entwickelt von DoiT Engineers. Die Integration läuft, ist aber weder ein produktionsreifes Produkt noch ein offiziell gepflegtes Projekt. Sie eignet sich vielmehr als Quickstart-Beispiel zum Lernen und gegebenenfalls als Grundlage für eine produktive Lösung.

Bringen Sie Ihr Produkt schneller auf den Markt!

In einem früheren Beitrag haben wir die Erstellung eines Marketplace-Angebots im Überblick vorgestellt. Dieser Artikel ist ein detaillierter Walkthrough durch DoiT-Easily und beleuchtet zentrale Architekturelemente sowie typische Stolpersteine in der Entwicklung. Wir gehen dabei auch auf Funktionen ein, die DoiT-Easily implementiert, ohne zwingender Bestandteil einer Marketplace-Integration zu sein, sowie auf Funktionen mancher Marketplace-Integrationen, die in DoiT-Easily nicht enthalten sind. Weitere Details finden Sie in der Dokumentation und im Code des Github-Projekts DoiT-Easily sowie in der öffentlichen Marketplace-Dokumentation von Google.

Die folgenden Diagramme zeigen die beiden zentralen Flows: das Anlegen eines neuen Nutzers und das Anlegen eines neuen Entitlements (Kauf). Der Flow für ein neues Entitlement entspricht dem Flow für die Änderung oder Kündigung eines Entitlements. Bei neuen Nutzern, die sich zugleich für ein Entitlement registrieren, laufen beide Flows parallel.

Im Anschluss an die Flow-Diagramme finden Sie ein Diagramm und eine Erläuterung der einzelnen Komponenten.

Flow für neue Nutzer

Entitlement-Flow

Im Architekturdiagramm aus DoiT-Easily sehen Sie die Komponenten Ihrer Integration und die Google-APIs, mit denen sie zusammenspielt.

Ihre funktionalen Komponenten finden sich in der unteren Hälfte des Diagramms, die Google-APIs in der oberen.

Ihr SaaS-Produkt – also das, was Sie in Google integrieren – ist in diesem Beispiel nicht enthalten. Ihre SaaS-Server können in einem anderen Google-Projekt deployed werden oder im selben Projekt wie das Integrationssystem.

Im Folgenden gehen wir auf diese Komponenten im Detail ein.

DoiT-Easily-Architektur

Frontend

Die Frontend-Integration im Diagramm ist eine Webanwendung mit Client und Server. DoiT-Easily implementiert einen HTML/AJAX-Client mit HTML-Templates. Der Server ist in Python geschrieben und auf Cloud Run deployed. In Ihrer eigenen Implementierung können Sie selbstverständlich auch andere Technologien einsetzen.

Der Frontend-Client zeigt die Landing Page, auf die Abonnenten im Sign-up-Flow weitergeleitet werden, nachdem GCP Marketplace sie übergeben hat. Das Frontend prüft das JWT in der Anfrage, um sicherzustellen, dass sie tatsächlich von Google stammt. Nach der Registrierung des Nutzers benachrichtigt der Frontend-Server die Procurement-API von Google und legt damit den Procurement-Account des Abonnenten an. Die gesamte Server-Logik der Frontend-Integration steckt in der Funktion login(), erreichbar unter dem Pfad /activate oder /login.

Backend

Die Backend-Integration ist ein Server, der ebenfalls auf Cloud Run deployed wird. In DoiT-Easily ist es derselbe Cloud-Run-Service; in Ihrer eigenen Anwendung können Sie sich aber auch für getrennte Frontend- und Backend-Services entscheiden. Das Backend empfängt Pub/Sub-Nachrichten von Google, die über Entitlements informieren. ("Entitlement" ist Googles Begriff für ein Abonnement Ihres Angebots.)

Die Datei api.py im Kern der Cloud-Run-Anwendung enthält viele Web-Endpoints, die nur selten zum Einsatz kommen – konzentrieren Sie sich daher auf die Hauptflows. Der Hauptflow wird per Pub/Sub über eine Push-Subscription ausgelöst, die von der Funktion handle_subscription_message() verarbeitet wird und unter dem Pfad /v1/notification erreichbar ist.

Backend-UI

DoiT-Easily bringt zusätzlich eine UI für das Backend mit, die in der grundlegenden Marketplace-Integrationsarchitektur nicht erforderlich ist. Damit lassen sich ausstehende Entitlements auflisten und manuell freigeben, falls Ihr System sie nicht automatisch freigibt. Den Server-Code finden Sie unter dem Pfad /app in app.py; abgesichert wird er über Identity-Aware Proxy (IAP).

In app.py finden Sie mehrere Endpoints für diese App, darunter die Hauptseite sowie Methoden zum Auflisten, Freigeben oder Ablehnen von Entitlements und zum Auflisten von Accounts.

Weitere Endpoints

Alle übrigen Endpoints in der Datei api.py stehen als authentifizierter Proxy zur Procurement-API zur Verfügung, sodass eine eigene Lösung mit DoiT-Easily statt direkt mit der Procurement-API interagieren kann.

Usage Reporter

Der Usage Reporter, der nicht Teil von DoiT-Easily ist, meldet die Nutzung Ihres Produkts durch den Kunden an Googles Service-Control-API. Das ist nötig, wenn die Abrechnung ressourcenbasiert erfolgt – etwa nach verarbeitetem Datenvolumen, Anzahl der Aufrufe Ihrer Lösung usw. Bieten Sie hingegen eine kostenlose Lösung oder ein Monatsabonnement an, ist diese Komponente nicht erforderlich – und genau deshalb fehlt sie in DoiT-Easily.

Wenn Sie einen Usage Reporter umsetzen, werden Sie in der Regel auch einen eigenen Datastore brauchen, um Entitlements (Abonnenten Ihres Angebots) nachzuhalten und auf dieser Basis das Usage-Reporting an Google zu speisen. DoiT-Easily implementiert keinen Datastore, sondern verlässt sich darauf, dass die Procurement-API alle Entitlements und ihren jeweiligen Status speichert.

ISV Provision Service

Wenn jeder neue Kunde zusätzliche Ressourcenanforderungen an Ihre SaaS-Lösung stellt, können Sie diese Komponente einsetzen, um die Ressourcen zu verwalten. Bekommt jeder Kunde beispielsweise einen eigenen Pod oder Namespace in Google Kubernetes Engine, würde der ISV Provision Service genau das einrichten. Da dieser Service für die meisten SaaS-Lösungen nicht zwingend nötig ist, ist er in DoiT-Easily nicht enthalten.

Weitere Cloud-Komponenten

Neben den Client- und Server-Komponenten im Diagramm umfasst DoiT-Easily die folgenden Cloud-Infrastruktur-Ressourcen. Sofern unten nicht anders erwähnt, werden sie über die Terraform-Module von DoiT-Easily für Sie deployed.

Vorgaben durch Google Marketplace

• IAM: Dazu zählen Berechtigungen in Ihrem Projekt für mehrere Google-Service-Accounts. Die Berechtigungen Ihres Service-Accounts für den Zugriff auf Google werden nicht in diesem Schritt definiert, sondern über das Producer Portal angefordert (siehe Schritt 5 unter "Set up", dokumentiert hier).
• Pub/Sub: Ein Topic, über das Google Ihnen Nachrichten zu Entitlement-Ereignissen sendet. Das Topic liegt in einem Google-eigenen Projekt und wird von Google angelegt, sobald Sie das unten beschriebene "Set up" durchlaufen. Ihr Backend abonniert dieses Topic.

Weitere Cloud-Services

DoiT-Easily nutzt die folgenden Cloud-Technologien; Sie können auch andere wählen, solange sie die gleiche Funktionalität bieten.

• Cloud-Run-Services für Frontend und Backend, wie oben beschrieben.
• Cloud DNS Zone: Jedes Marketplace-Listing hat eine eigene öffentliche Adresse, an die der Google Marketplace Sign-up-Anfragen weiterleitet. Die DNS Zone bedient diese Domains. Terraform legt diese Ressource nicht an; wir setzen voraus, dass Sie bereits eine Zone besitzen.
• Ein Load Balancer nimmt die Anfragen entgegen – auch die vom Google Marketplace weitergeleiteten – und routet sie an den Service für das jeweilige Marketplace-Listing. Der Load Balancer verfügt über die zugehörige öffentliche IP-Adresse, das TLS-Zertifikat, IAP sowie Routing-Regeln.
• Eine Konfigurationsdatei für Cloud Run, die als Secret im GCP Secret Manager hinterlegt ist. Terraform erstellt das Secret-Objekt. Achten Sie beim Deployment von DoiT-Easily darauf, den Wert im Secret Manager bei Bedarf zu aktualisieren. Dadurch erhöht sich die Versionsnummer, die wiederum in der tfvars-Datei nachgezogen werden sollte. Die Konfiguration enthält einige Umgebungswerte, die geheim bleiben müssen, sowie der Bequemlichkeit halber auch einige, bei denen das nicht nötig ist.

Das Aufsetzen von DoiT-Easily gliedert sich in die folgenden Phasen. Für mehrere davon gibt es Terraform-Module. Kopieren Sie die Datei example.tfvars nach terraform.tfvars, passen Sie die Werte an und führen Sie anschließend terraform init sowie terraform apply aus.

Voraussetzungen

Die Phase der Voraussetzungen heißt so, weil sie zeitlich vor der Freigabe Ihres Projekts durch Google liegt. Terraform legt das Projekt selbst an sowie IAM-Rollen für die Google-Service-Accounts in Ihrem Projekt und außerdem eine Rolle für den Nutzer, der das Deployment ausführt.

Set up bei Google

Sie richten Ihr Projekt bei Google ein, indem Sie ein Formular zur Freigabe einreichen – das kann mehrere Wochen dauern. (Holen Sie sich gerne Unterstützung von DoiT, um durch diesen Prozess zu kommen!) Nach der Freigabe definieren Sie Ihr Listing vollständig im Producer Portal, einschließlich Preisen, Produktinformationen und dem Service-Account, dem Google Berechtigungen einräumen wird.

Deployment

Sie bauen die Cloud-Run-App mit Cloud Build und pushen das Image in die Artifact Registry. Anschließend deployen Sie sie mit Terraform – samt der benötigten Cloud-Ressourcen wie DNS Zone und Load Balancer.

Testen

Während der Entwicklung können Sie DoiT-Easily lokal ausführen und die mitgelieferten Unit-Tests laufen lassen.

Sobald die Lösung deployed ist, lässt sie sich manuell testen, indem Sie Nutzerregistrierung, Kauf und Freigaben in Ihrem Marketplace-Projekt Schritt für Schritt durchspielen. (Bis das Listing veröffentlicht ist, läuft es im Private-Preview-Modus.)

Außerdem steht ein automatisiertes Integrationstest-Framework von Google zur Verfügung; Google verlangt, dass es vor der Veröffentlichung erfolgreich durchläuft.

Wenn Sie ausschließlich Private Offers anbieten, werden die automatisierten Tests nie erfolgreich durchlaufen. Sie können diesen Schritt überspringen und Ihr Listing dennoch veröffentlichen.

Im letzten Schritt – der Veröffentlichung – holen Sie eine manuelle Freigabe von Google ein. Das heißt: Sie können Fixes und Verbesserungen nicht mehrfach täglich per Continuous Deployment ausrollen. Jede neue Version kann mehrere Tage in der Warteschleife hängen, bis die Freigabe vorliegt.

Jede Implementierung einer Marketplace-Integration – auch DoiT-Easily – bringt im Vergleich zu typischen Cloud-Anwendungen einige grundlegende Einschränkungen mit sich. Hinzu kommen mögliche Funktionen, die in DoiT-Easily nicht umgesetzt sind.

Freigabe pro Projekt erforderlich

Nachdem Sie die Voraussetzungen eingerichtet haben, muss Google Ihr Projekt freigeben. Das bedeutet: Sie haben nur ein einziges Projekt, in dem Ihre Lösung läuft – getrennte Projekte für Dev, Test, Staging und Produktion sind nicht möglich.

Die Ressourcen, die vor der Nutzung Ihres Projekts freigegeben werden müssen, lassen sich nicht ohne Weiteres löschen und neu anlegen. Damit ist auch kein End-to-End-Test möglich, bei dem ein Skript ein neues Sandbox-Projekt erstellt, die Anwendung aufsetzt, Tests laufen lässt und am Ende alles wieder löscht. Ebenso wenig lassen sich alle Ressourcen in Ihrem Marketplace-Projekt aufräumen, um bei null neu zu starten. Sie können Tests mit den eingebauten Test- und Preview-Funktionen des Marketplace durchführen, allerdings ohne sauberen Anfangs- und Endzustand.

Aus demselben Grund lassen sich auch keine getrennten Dev-Umgebungen je Teammitglied einrichten. Stattdessen können Teammitglieder ein Projekt gemeinsam nutzen. Sie müssen jedoch eine Architektur entwerfen, in der Teammitglieder eigene Listings anlegen und sich die übrige Infrastruktur teilen – also Projekt, IAM-Einstellungen, Load Balancer, Pub/Sub-Topic und DNS Zone. Jede App muss das Pub/Sub-Topic abonnieren und nur die für sie relevanten Nachrichten verarbeiten. DoiT-Easily setzt die Unterstützung mehrerer Listings noch nicht vollständig um: Zwar hindert es Sie nicht daran, mehrere Listings anzulegen, der Terraform-Deployment-Code ist dafür aber nicht ausgelegt.

Das heißt auch: Für den Betrieb von DoiT-Easily benötigen Sie – wie bei jeder anderen Marketplace-Integration – ein offizielles Marketplace-Projekt, das den Google-Freigabeprozess durchläuft.

Alternative Szenarien

DoiT-Easily wurde entwickelt, um ein konkretes Szenario abzubilden. Wie bei Enterprise-Business-to-Business-Integrationen üblich, werden Marketplace-Lösungen jedoch häufig in individuellen Varianten umgesetzt. Ein Beispiel ist eine reine Private-Offer-Lösung; sie gibt Anbietern mehr Kontrolle über den Vertriebsprozess und macht ein Frontend wie oben beschrieben überflüssig. Allerdings braucht es dafür ein internes Tool zur Verwaltung der Private Offers, und viele Anbieter entwickeln zu diesem Zweck eine eigene interne Webanwendung.