DoiT-Easily

Scritto con Dave Cavaletto

Sviluppare una soluzione da vendere su Google Marketplace non è tecnicamente complesso. La vera sfida è che si tratta di un'integrazione di tipo enterprise, in cui ci si collega ai sistemi aziendali di un'altra società, Google, anziché accedere ad API liberamente disponibili come avviene su Google Cloud Platform. Google deve approvare il Suo progetto GCP prima che Lei realizzi l'integrazione, e successivamente approvare la soluzione una volta pronta per il rilascio.

DoiT-Easily è un progetto open source che mostra un'integrazione di esempio pienamente funzionante, realizzata dagli engineer di DoiT. L'integrazione funziona, ma non è un prodotto pronto per la produzione, né un progetto supportato. È piuttosto un esempio quickstart utile da cui partire per imparare ed eventualmente adattare il codice in una soluzione di produzione.

Porti il Suo prodotto sul mercato più velocemente!

In un articolo precedente abbiamo offerto una panoramica generale sulla creazione di un'offerta Marketplace. Questo articolo è invece un'analisi più approfondita di DoiT-Easily, in cui descriviamo gli elementi architetturali chiave e le sfide che incontrerà nello sviluppo. Includiamo funzionalità implementate da DoiT-Easily che non sono indispensabili in un'integrazione Marketplace, oltre ad alcune funzionalità presenti in altre integrazioni Marketplace ma assenti in DoiT-Easily. Per maggiori dettagli, consulti la documentazione e il codice del progetto Github di DoiT-Easily, insieme alla documentazione pubblica del Marketplace di Google.

I diagrammi seguenti illustrano i due flussi principali: la creazione di un nuovo utente e la creazione di un nuovo entitlement (acquisto). Il flusso di un nuovo entitlement è identico a quello previsto per la modifica o la cancellazione di un entitlement. Per i nuovi utenti che si iscrivono contestualmente a un entitlement, entrambi i flussi vengono attivati in parallelo.

Dopo i diagrammi di flusso, troverà uno schema dei componenti accompagnato da una descrizione dettagliata.

Flusso nuovo utente

Flusso entitlement

In questo diagramma di architettura tratto da DoiT-Easily sono visibili i componenti dell'integrazione e le API di Google con cui essa si interfaccia.

I componenti funzionali si trovano nella metà inferiore del diagramma, mentre le API di Google occupano la metà superiore.

Il SaaS che Lei sta integrando con Google non è rappresentato in questo esempio. I server del Suo SaaS possono essere distribuiti in un altro progetto Google oppure nello stesso progetto del sistema di integrazione.

Di seguito approfondiamo questi componenti.

Architettura di DoiT-Easily

Frontend

L'integrazione frontend nel diagramma è una web app, comprensiva di client e server. DoiT-Easily implementa un client HTML/AJAX con template HTML. Il server è scritto in Python e distribuito su Cloud Run. Naturalmente, nella Sua implementazione potrà optare per altre tecnologie.

Il client front-end mostra la landing page a cui gli abbonati vengono reindirizzati durante il flusso di iscrizione, dopo l'inoltro da parte di GCP Marketplace. Il front-end verifica il JWT presente nella richiesta per autenticarne la provenienza da Google. Una volta completata l'iscrizione, il server front-end notifica l'API Procurement di Google, creando così l'account di procurement dell'abbonato. L'intera logica server dell'integrazione frontend è racchiusa nella funzione login(), raggiungibile al path /activate oppure /login.

Backend

Anche l'integrazione backend è un server distribuito su Cloud Run. In DoiT-Easily si tratta dello stesso servizio Cloud Run, anche se nella Sua applicazione potrebbe scegliere di separare i servizi front-end e back-end. Il backend riceve messaggi Pub/Sub da Google con le notifiche relative agli Entitlement. ("Entitlement" è il termine con cui Google indica un abbonamento alla Sua offerta.)

Si noti che il file api.py al cuore dell'applicazione Cloud Run contiene molti endpoint web utilizzati raramente: conviene quindi concentrarsi sui flussi principali. Il flusso principale viene attivato tramite Pub/Sub attraverso una push-subscription gestita dalla funzione handle_subscription_message(), raggiungibile al path /v1/notification.

Backend-UI

DoiT-Easily offre un'ulteriore UI per il backend, non richiesta dall'architettura di base dell'integrazione Marketplace. Può essere utilizzata per elencare gli Entitlement in attesa e approvarli manualmente, qualora il Suo sistema non sia progettato per approvarli in modo automatico. Il codice del server è consultabile al path /app nel file app.py ed è protetto da Identity-Aware Proxy (IAP).

In app.py troverà diversi endpoint a supporto di questa app, tra cui la pagina principale, oltre ai metodi per elencare, approvare o rifiutare gli entitlement ed elencare gli account.

Altri endpoint

Tutti gli altri endpoint del file api.py sono utilizzabili come proxy autenticato verso l'API Procurement, in modo che una soluzione personalizzata possa interagire con DoiT-Easily anziché direttamente con l'API Procurement.

Usage Reporter

L'Usage Reporter, che non fa parte di DoiT-Easily, comunica all'API Service Control di Google l'utilizzo del Suo prodotto da parte del cliente. È necessario quando la fatturazione si basa sulle risorse, ad esempio sulla quantità di dati elaborati, sul numero di chiamate alla soluzione e così via. Se invece offre una soluzione gratuita o a pagamento tramite abbonamento mensile, questo componente non serve: è il motivo per cui DoiT-Easily non lo include.

Se decide di implementare un Usage Reporter, vorrà probabilmente predisporre un proprio datastore per tracciare gli entitlement (gli abbonati alla Sua offerta) e usare questi record come base per il reporting dell'utilizzo verso Google. Allo stato attuale, DoiT-Easily non implementa un datastore e si affida invece all'API Procurement per memorizzare tutti gli Entitlement e il relativo stato.

ISV Provision Service

Se ogni nuovo cliente comporta nuovi requisiti di risorse per la Sua soluzione SaaS, può creare questo componente per gestirli. Per esempio, se ogni cliente riceve un proprio pod o namespace su Google Kubernetes Engine, sarà l'ISV Provision Service a occuparsi della configurazione. Poiché questo servizio non è indispensabile per la maggior parte delle soluzioni SaaS, DoiT-Easily non lo include.

Altri componenti cloud

Oltre ai componenti client e server presenti nel diagramma, DoiT-Easily comprende le seguenti risorse di infrastruttura cloud. I moduli Terraform di DoiT-Easily provvedono a distribuirle, salvo diversa indicazione qui sotto.

Specificati da Google Marketplace

• IAM: include i permessi sul Suo progetto per diversi service account di Google. I permessi che il Suo service account deve avere per accedere a Google non vengono definiti in questo passaggio, ma richiesti tramite il Producer Portal (vedi Step 5 in "Set up", documentato qui).
• Pub/Sub: un topic su cui Google invia i messaggi relativi agli eventi di entitlement. Il topic risiede in un progetto di proprietà di Google e viene creato da Google quando si segue la procedura di "Set up" descritta più avanti. Il Suo backend si iscrive a questo topic.

Altri servizi cloud

DoiT-Easily utilizza queste tecnologie cloud; può sceglierne altre, purché offrano le stesse funzionalità.

• Servizi Cloud Run per front-end e back-end, come anticipato sopra.
• Cloud DNS Zone: ogni listing del Marketplace ha un proprio indirizzo pubblico, a cui Google Marketplace inoltra le richieste di iscrizione. La DNS Zone serve questi domini. Terraform non crea questa risorsa: si presume che Lei disponga già di una zona esistente.
• Un Load Balancer riceve le richieste, comprese quelle inoltrate da Google Marketplace, e le instrada al servizio del listing Marketplace pertinente. Al Load Balancer sono associati l'indirizzo IP pubblico, il certificato TLS, IAP e le regole di routing.
• Un file di configurazione per Cloud Run, archiviato come Secret in GCP Secret Manager. Terraform crea l'oggetto Secret. Quando distribuisce DoiT Easily, si assicuri di aggiornare il valore in Secret Manager in base alle esigenze. L'operazione incrementa il numero di versione, che andrà poi aggiornato nel file tfvars. La configurazione contiene alcuni valori di ambiente che devono restare segreti e, per comodità, anche altri che non lo sono.

La configurazione di DoiT-Easily prevede le fasi seguenti. Diverse di esse dispongono di moduli Terraform. Copi il file example.tfvars in terraform.tfvars, modifichi i valori, quindi esegua terraform init e terraform apply.

Pre-requisiti

La fase dei pre-requisiti si chiama così perché precede l'approvazione del Suo progetto da parte di Google. Terraform crea il progetto stesso e i ruoli IAM per i service account di Google sul Suo progetto, oltre a un ruolo per l'utente che esegue il deployment.

Set up con Google

Lei configura il progetto con Google inviando un modulo per richiedere l'approvazione, che può richiedere diverse settimane. (Si rivolga a DoiT per essere accompagnato in questo processo!) Una volta ottenuta l'approvazione, definirà completamente il listing nel Producer Portal, indicando prezzi, informazioni di produzione e il service account a cui Google concederà i permessi.

Deployment

L'app Cloud Run viene compilata con Cloud Build ed effettuando il push dell'immagine su Artifact Registry. La si distribuisce poi con Terraform, insieme alle risorse cloud necessarie come la DNS Zone e il Load Balancer.

Test

Durante lo sviluppo è possibile eseguire DoiT-Easily in locale ed eseguire gli unit test inclusi.

Una volta distribuita la soluzione, può testarla manualmente, ripercorrendo le fasi di registrazione utente, acquisto e approvazione nel Suo progetto Marketplace. (Finché il listing non viene pubblicato, resta in modalità private preview.)

È disponibile anche un framework automatizzato di test di integrazione fornito da Google, il cui superamento è un requisito per la pubblicazione.

Se offre soltanto private offers, il test automatizzato non potrà mai concludersi con successo. Può saltare questo passaggio e pubblicare comunque il listing.

Per il passaggio finale di pubblicazione dovrà richiedere l'approvazione manuale a Google. Questo significa che non potrà rilasciare correzioni e miglioramenti frequenti effettuando il push in produzione più volte al giorno, come accade con il continuous deployment. Ogni nuova versione potrebbe richiedere un round-trip di diversi giorni in attesa dell'approvazione.

Qualunque implementazione di un'integrazione Marketplace, DoiT-Easily compresa, presenta alcune limitazioni intrinseche rispetto alle tipiche applicazioni cloud. Vi sono inoltre alcune funzionalità possibili che DoiT-Easily non implementa.

Approvazione necessaria per ogni progetto

Dopo aver completato i pre-requisiti, Google deve approvare il Suo progetto. Questo significa che disporrà di un solo progetto su cui la soluzione potrà funzionare: non avrà progetti separati per dev, testing, staging e produzione.

Le risorse che devono ottenere l'approvazione prima di poter essere usate non sono facili da eliminare e ricreare. Di conseguenza non potrà disporre di un test end-to-end in cui uno script crea un nuovo progetto sandbox, configura l'applicazione, esegue i test e infine cancella tutto. Allo stesso modo, non è possibile ripulire tutte le risorse del Suo progetto Marketplace e ripartire da zero. Può eseguire un test sfruttando le funzionalità integrate di test e preview del Marketplace, ma il test non inizierà né terminerà con uno stato pulito.

Analogamente, non è possibile creare ambienti di sviluppo separati per ciascun membro del team. Può invece condividere un unico progetto tra i membri del team. Tuttavia, dovrà progettare un'architettura in cui ogni membro crea listing distinti; condivideranno tutto il resto dell'infrastruttura, ovvero il progetto, le impostazioni IAM, il Load Balancer, il topic Pub/Sub e la DNS zone. Ogni app dovrà sottoscrivere il topic Pub/Sub ed elaborare solo i messaggi di propria competenza. DoiT-Easily non implementa pienamente la capacità multi-listing: pur non impedendo la creazione di più listing, il codice di deployment Terraform non è pensato per questo scenario.

Ciò significa anche che, per eseguire DoiT-Easily come qualsiasi altra integrazione Marketplace, avrà bisogno di un progetto Marketplace ufficiale che dovrà passare attraverso l'approvazione di Google.

Scenari alternativi

DoiT-Easily nasce per illustrare uno scenario specifico, ma come spesso accade nelle integrazioni business-to-business di tipo enterprise, le soluzioni Marketplace vengono frequentemente sviluppate in varianti personalizzate. Un esempio è una soluzione esclusivamente private-offer: questa formula offre ai vendor un controllo maggiore sul processo di vendita ed elimina la necessità di un front-end come quello descritto sopra. Richiede però uno strumento interno per gestire le private offers, e molti vendor sviluppano una web app interna a questo scopo.