Requisiti per la pacchettizzazione dell'app

In questa pagina vengono descritti i requisiti per la pacchettizzazione dell'app Kubernetes e le linee guida per soddisfarli.

Il pacchetto dell'app è un bundle di immagini container e file di configurazione di cui viene eseguito il deployment nei cluster Kubernetes degli utenti. Per supportare il deployment della tua app in Google Kubernetes Engine dalla console Google Cloud, il pacchetto dell'app deve includere un container di deployment. Il container di deployment esegue il push dei file di configurazione e mostra i metadati all'API Kubernetes.

Il pacchetto dell'app consente agli utenti di Google Cloud di:

• Scopri la tua app nel catalogo di Cloud Marketplace
• Eseguire il deployment dell'app nel cluster GKE o GKE Enterprise usando la console Google Cloud
• Interagisci con l'app in esecuzione utilizzando la console Google Cloud

Oltre a supportare il deployment tramite la console Google Cloud, il pacchetto deve includere i passaggi per consentire agli utenti di eseguire il deployment dell'app tramite un'interfaccia a riga di comando (CLI), utilizzando strumenti come kubectl o Helm.

Per esempi di pacchetti dell'app, consulta il repository GitHub per le soluzioni Google Click-to-deploy. Il repository contiene pacchetti per le app open source più diffuse, come WordPress ed Elasticsearch.

Prima di iniziare

• Assicurati di aver configurato il tuo ambiente Google Cloud.
• Crea un repository Git pubblico per i file di configurazione, la guida dell'utente e altre risorse per l'esecuzione dell'app. Puoi ospitare il repository con un provider come GitHub, Cloud Source Repositories o sul tuo server. Ti consigliamo un repository dedicato per ogni prodotto che stai distribuendo.

Panoramica

L'app deve soddisfare i seguenti requisiti:

• Il repository Git deve contenere un file LICENSE, che contiene la licenza open source per il repository.

• Il repository Git deve contenere un file di configurazione che esegue il deployment dell'app. Il file di configurazione può essere un manifest YAML Kubernetes o un grafico Helm.

  La configurazione deve includere una risorsa Applicazione personalizzata, che descrive l'app.

  Vedi i requisiti per la configurazione.

• L'app deve essere eseguita su nodi che utilizzano un processore x86.

• Facoltativamente, se vuoi che la tua app sia compatibile con Istio, consulta le limitazioni sui cluster che eseguono Istio.

• Se la tua app è commerciale (non BYOL), deve segnalarne l'utilizzo a Google, in modo che la fatturazione ai clienti avvenga in modo accurato. Ti consigliamo di integrare la tua app con l'agente di fatturazione basato sull'utilizzo, che invia i report sull'utilizzo a Google.

  Consulta Requisiti per l'integrazione dell'agente di fatturazione.

• Tutte le immagini container dell'app devono essere caricate nel registro di Container Registry. Il registro deve includere anche un'immagine deployer che esegue il push della configurazione dell'app all'API Kubernetes quando gli utenti eseguono il deployment dell'app dalla console Google Cloud.

  Consulta i requisiti per la creazione di immagini delle app.

• Devi includere test di integrazione per l'app.

  Consulta i requisiti per la procedura di verifica.

• Devi includere una guida dell'utente con i passaggi per eseguire il deployment dell'app dalla riga di comando, configurarla e usarla.

  Consulta i requisiti per la guida dell'utente.

Requisiti per la configurazione

Puoi fornire la tua configurazione come manifest Kubernetes o come grafico Helm.

La configurazione deve soddisfare i seguenti requisiti:

• Per proteggere gli utenti da API instabili, utilizza solo risorse Kubernetes in versione beta o in disponibilità generale.

• La tua configurazione deve eseguire il deployment di una risorsa personalizzata dell'applicazione. La risorsa Applicazione contiene le informazioni visualizzate dagli utenti quando eseguono il deployment dell'app tramite l'interfaccia utente di Cloud Marketplace.

  La risorsa Applicazione è una risorsa personalizzata che aggrega i componenti Kubernetes associati alla tua app e consente agli utenti di gestire queste risorse come gruppo.

  Per informazioni sulla creazione di una risorsa applicazione e per alcuni esempi, consulta il repository GitHub dell'applicazione.

• La configurazione deve utilizzare parametri che possano essere sostituiti utilizzando envsubst o come flag.

  I seguenti parametri devono poter essere sostituiti:

  • Spazio dei nomi: tutte le risorse della tua configurazione devono appartenere a un singolo spazio dei nomi. Gli utenti di Cloud Marketplace configurano questo spazio dei nomi quando eseguono il deployment dell'app. Evita spazi dei nomi hardcoded nei file manifest, in modo che le risorse specificate vengano create nello spazio dei nomi selezionato dagli utenti. A volte gli spazi dei nomi appaiono anche all'interno delle definizioni delle risorse, ad esempio quando si fa riferimento a un ServiceAccount in un RoleBinding. Tutti i riferimenti di questo tipo devono essere parametrizzati.

  • Nome app: il nome dell'istanza della risorsa applicazione. Questa stringa deve essere inclusa nel nome di ciascuna risorsa dell'app per evitare conflitti di nomi se viene eseguito il deployment di più istanze dell'app in un singolo spazio dei nomi.

  • Immagini container: ogni riferimento a un'immagine, ad esempio in PodSpec, deve essere sostituibile in modo che Cloud Marketplace possa sostituirli in modo che rimandino a immagini pubblicate nel nostro Container Registry. Inoltre, consente ai clienti di sostituire facilmente le immagini modificate.

  • Secret della licenza: se la tua app sta eseguendo un monitoraggio commerciale, deve accettare il nome di una risorsa secret come parametro. Il secret contiene le credenziali dei report sull'utilizzo, che la tua app utilizza per inviare dati sull'utilizzo a Google.

    Scopri di più sui parametri di configurazione su GitHub.

• Deve essere possibile eseguire il deployment dell'app utilizzando strumenti lato client. Ad esempio, se utilizzi Helm, il deployment deve funzionare con il flag della riga di comando --client-only.

Limitazioni sui cluster con Istio

Se vuoi che l'applicazione sia compatibile con Istio, rivedi le limitazioni descritte in questa sezione. Per una panoramica di Istio, consulta Che cos'è Istio?.

Se i tuoi clienti eseguono Istio nei loro cluster, Istio controlla il traffico di rete tra i pod dell'app per impostazione predefinita. Ciò potrebbe bloccare la comunicazione di rete nei seguenti scenari:

• Se i tuoi pod eseguono i comandi kubectl che utilizzano l'indirizzo IP del cluster, i comandi potrebbero avere esito negativo.

• Se l'app utilizza la comunicazione da pod a pod o basata su IP, la fase di creazione del cluster potrebbe non riuscire.

• Le connessioni esterne a servizi di terze parti, ad esempio i repository dei pacchetti del sistema operativo, potrebbero essere bloccate. I clienti devono configurare il traffico in uscita da Istio per abilitare l'accesso ai servizi esterni.

Ti consigliamo di configurare le connessioni in entrata utilizzando il gateway Istio, anziché le risorse LoadBalancer o Ingress.

Se utilizzi Helm per la configurazione, usa la proprietà x-google-marketplace ISTIO_ENABLED nello schema per l'immagine di deployment. Se questa proprietà è true, il deployment deve modificare il deployment, ad esempio attendendo che il sidecar Istio sia pronto.

Per aiutare i tuoi clienti a configurare la comunicazione tra i pod delle app, ti consigliamo di aggiungere dei passaggi alle sezioni post-deployment della documentazione.

Requisiti per integrare l'agente di fatturazione

Se vendi un'app commerciale, ti consigliamo di integrarla con l'agente di fatturazione basata sull'utilizzo (UBB).

L'agente gestisce l'autenticazione e la generazione di report sull'endpoint di reporting sull'utilizzo di Google: Service Control. Una volta inviato il modello di prezzi, il team di Cloud Marketplace crea un servizio per la tua app in base al quale generare report e le metriche di fatturazione per misurare l'utilizzo.

L'agente gestisce anche l'aggregazione locale, il ripristino da arresti anomali e i nuovi tentativi. Per la metrica delle ore di utilizzo, l'agente può essere configurato in modo da registrare automaticamente i battiti cardiaci.

L'agente mostra anche lo stato dei report, consentendo alla tua app di rilevare se l'agente sta segnalando correttamente i dati sull'utilizzo.

I clienti acquistano l'app in Cloud Marketplace per acquisire una licenza, che viene allegata all'app al momento del deployment.

Quando esegui l'integrazione con l'agente di fatturazione, valuta il funzionamento dell'app quando i report sull'utilizzo non vanno a buon fine, il che potrebbe indicare una delle seguenti condizioni:

• Il cliente ha annullato l'abbonamento.

• Il cliente potrebbe aver disattivato accidentalmente il canale di segnalazione. Ad esempio, i clienti potrebbero inavvertitamente rimuovere o configurare in modo errato l'agente oppure la rete potrebbe impedire all'agente di accedere all'endpoint di reporting di Google.

Segui le best practice per segnalare l'utilizzo e gestire i casi in cui Google non riceve dati sull'utilizzo e non vengono fatturati i clienti.

Integrazione dell'agente di fatturazione

Puoi integrare l'agente come container sidecar, che viene eseguito nello stesso pod della tua app oppure utilizzando l'SDK.

Nell'approccio sidecar, l'agente viene eseguito nel proprio container, nello stesso pod Kubernetes del container dell'app. L'app comunica con l'interfaccia REST locale dell'agente.

Nell'approccio SDK, l'agente deve essere compilato o collegato al programma binario dell'app. L'SDK è implementato in modo nativo per Go, con associazioni per Python.

In generale, l'approccio sidecar richiede uno sforzo di integrazione minore, mentre l'SDK è più solido contro la disabilitazione accidentale.

Per la procedura dettagliata di integrazione, consulta il file README nel repository GitHub di Agente di fatturazione basato sull'utilizzo. Per visualizzare un'implementazione di esempio, consulta i repository di app e tools di esempio.

Credenziali per segnalare l'utilizzo

L'agente di fatturazione richiede credenziali che gli consentano di inviare report sull'utilizzo a Google. Cloud Marketplace genera queste credenziali quando gli utenti eseguono il deployment dell'app da Cloud Marketplace e ne garantisce la presenza come Secret nello spazio dei nomi Kubernetes di destinazione prima del deployment dell'app. Il nome di questo secret viene passato alla tua app come proprietà di schema REPORTING_SECRET.

Per un manifest di esempio che utilizza il secret di reporting, vedi l'esempio di app WordPress in GitHub.

Il secret contiene i seguenti campi:

entitlement-id	Un identificatore che rappresenta il contratto con il cliente per l'acquisto e l'utilizzo del software.
consumer-id	Identificatore associato al diritto che viene trasmesso a Google Service Control insieme ai report sull'utilizzo.
reporting-key	La chiave JSON dell'account di servizio Google Cloud utilizzata per l'autenticazione in Google Service Control.

Se il tuo prodotto fornisce un componente SaaS oltre all'app, puoi scegliere che il componente SaaS verifichi periodicamente la validità degli ID dei diritti utilizzando il servizio di approvvigionamento di Cloud Marketplace. Per ottenere l'accesso al servizio Approvvigionamento, contatta il tuo Partner Engineer.

Per informazioni sugli altri parametri trasmessi all'app, consulta Parametri passati all'app più avanti in questa sezione.

Requisiti per la creazione delle immagini container

L'app è costituita da una o più immagini container di app. Inoltre, il repository deve includere un container di deployment, che viene utilizzato quando i clienti eseguono il deployment dell'app dall'interfaccia utente di Cloud Marketplace.

Le immagini container vengono in genere create utilizzando un Dockerfile e lo strumento a riga di comando docker build. Ti consigliamo di pubblicare le istruzioni di creazione di Dockerfile e container nel repository pubblico dell'app. La pubblicazione consente ai clienti di modificare o ricreare le immagini, operazione a volte necessaria per certificare le immagini per gli ambienti di produzione aziendali.

Se l'immagine dell'app dipende da un'immagine di base, ad esempio Debian o da un'immagine runtime del linguaggio, come Python o OpenJDK, ti consigliamo vivamente di utilizzare una delle immagini container certificate di Cloud Marketplace. In questo modo vengono applicati aggiornamenti tempestivi all'immagine di base, soprattutto per le patch di sicurezza.

Dopo aver creato le immagini dell'app, esegui il push delle immagini nel registro gestione temporanea creato in Container Registry durante la configurazione dell'ambiente.

Il repository di Container Registry deve avere la seguente struttura:

• L'immagine principale dell'app deve essere nella directory radice del repository. Ad esempio, se il repository di Container Registry è gcr.io/exampleproject/exampleapp, l'immagine dell'app dovrebbe trovarsi in gcr.io/exampleproject/exampleapp.

• L'immagine del container di deployment deve trovarsi in una cartella denominata deployer. Nell'esempio precedente, l'immagine del deployment deve essere in gcr.io/exampleproject/exampleapp/deployer.

• Se l'app utilizza immagini container aggiuntive, ogni immagine aggiuntiva deve essere nella propria cartella sotto l'immagine principale. Ad esempio, se la tua app richiede un'immagine proxy, aggiungila a gcr.io/exampleproject/exampleapp/proxy.

• Tutte le immagini dell'app devono includere il canale di rilascio e la versione corrente. Ad esempio, se stai rilasciando la versione 2.0.5 nel canale di rilascio 2.0, tutte le immagini devono essere taggate con 2.0 e 2.0.5. Scopri come organizzare le release.

Ad esempio, l'immagine seguente mostra il repository Container Registry per l'app Kubernetes Grafana Cluster. Il canale di rilascio è 5.3 e l'app contiene l'immagine principale dell'app, l'immagine del deployer nella propria cartella e l'immagine Debian 9 in debian9. Tutte le immagini nel repository hanno il tag della stessa traccia, 5.3, e della stessa versione nel canale, 5.3.4. Deve corrispondere anche al campo "Versione" della definizione di risorse personalizzate (CRD) per la risorsa applicazione come dichiarato nel deployment.

Il repository si trova all'indirizzo gcr.io/cloud-marketplace/google/grafana.

Quando scegli gli ID prodotto, utilizza gli ID immagine container che hai selezionato in precedenza.

Per caricare le immagini in Container Registry, taggale con il nome del registro ed esegui il push dell'immagine utilizzando gcloud. Ad esempio, utilizza i seguenti comandi per eseguire il push delle immagini per example-pro:

docker build -t gcr.io/my-project/example-pro:4.0   # release track 4.0
docker tag gcr.io/my-project/example-pro:4.0 gcr.io/my-project/example-pro:4.0.3  # release version 4.0.3
docker push gcr.io/my-project/example-pro:4.0
docker push gcr.io/my-project/example-pro:4.0.3

Per la procedura dettagliata su come aggiungere tag ed eseguire il push delle immagini nel registro, consulta la documentazione di Container Registry.

Requisiti per il container di deployment

Il container di deployment, o deployer, viene utilizzato quando i clienti eseguono il deployment del tuo prodotto da Cloud Marketplace. L'immagine del deployer crea pacchetti della configurazione Kubernetes della tua app e degli strumenti client, come kubectl o Helm, che eseguono il push della configurazione nell'API Kubernetes. Il deployer dovrebbe utilizzare in genere lo stesso insieme di comandi della riga di comando che un utente eseguirebbe per eseguire il deployment dell'app.

Per creare il deployment, utilizza una delle immagini di base per i container di deployment dalla directory del marketplace del repository degli strumenti:

• Se utilizzi kubectl per la configurazione, usa kubectl base image.
• Se utilizzi un grafico Helm per la configurazione, utilizza l'immagine di base di Helm.

Le immagini di base hanno utilità integrate per attività come l'assegnazione dei riferimenti al proprietario, la generazione di password e la pulizia post-deployment.

Per la procedura per creare l'immagine del deployment, consulta Creazione del deployment dell'applicazione.

Parametri passati all'app

Il container di deployment deve dichiarare i parametri che devono essere raccolti dai clienti quando selezionano la tua app. Questi parametri vengono quindi forniti al container di deployment quando gli utenti eseguono il deployment dell'app.

Per configurare questi parametri, l'immagine del container di deployment deve includere uno schema JSON in formato YAML in questo percorso: /data/schema.yaml.

Per scoprire come creare un schema.yaml, consulta la pagina relativa allo schema del deployment.

Richieste di cluster GPU

Se la tua app ha esigenze specifiche in termini di GPU o utilizza molta GPU, puoi specificare il tipo e il numero di GPU nel cluster utilizzando lo schema di deployment. Se specifichi le tue esigenze in fatto di GPU, la creazione assistita del cluster è disabilitata.

La tua app potrebbe richiedere una GPU Nvidia generica o una piattaforma Nvidia specifica.

Requisiti per la procedura di verifica

Le app vengono eseguite nel nostro sistema di verifica per garantire che:

• Installazione riuscita: tutte le risorse sono state applicate e sono in attesa che diventino integri.
• Test di funzionalità superati: il deployer avvia il pod del tester e ne controlla lo stato di uscita. Zero significa successo, diverso da zero significa fallimento.
• Disinstallazione riuscita: l'app e tutte le relative risorse vengono rimosse dal cluster.

Prima che un'app possa essere pubblicata in Google Cloud Marketplace, sono necessari risultati positivi.

Per informazioni dettagliate su come pacchettizzare, eseguire e verificare questi test di funzionalità, segui la documentazione sull'integrazione di Verification.

Requisiti per la guida dell'utente

La guida dell'utente deve includere le seguenti informazioni:

Panoramica

• Una panoramica generale dell'app, con le funzioni di base e le opzioni di configurazione. Questa sezione deve collegarsi anche al prodotto pubblicato su Cloud Marketplace.

Configurazione una tantum

• Configurazione di strumenti client come kubectl o Helm, a seconda dei casi.
• Installare Application CustomResourceDefinition (CRD), in modo che il cluster possa gestire la risorsa Application.
• Se vendi un'app commerciale, segui la procedura per l'acquisizione e il deployment di un secret di licenza da Cloud Marketplace.

Installazione

• Comandi per il deployment dell'app.
• Trasmissione dei parametri disponibili nella configurazione dell'interfaccia utente.
• Bloccare i riferimenti alle immagini a digest immutabili.

• Se aggiungi campi di immissione personalizzati allo schema del deployer, aggiungi informazioni sui valori previsti, se applicabili.

  Scopri come aggiungere campi di immissione al deployment

Utilizzo di base

• Connessione a una Console di amministrazione (se applicabile).
• Connessione di uno strumento client ed esecuzione di un comando di esempio (se applicabile).
• Modifica di nomi utente e password.
• Attivazione del traffico in entrata e installazione dei certificati TLS (se applicabile).

Backup e ripristino

• Backup dello stato dell'app in corso...
• Ripristino dello stato dell'app da un backup.

Aggiornamenti di immagini

• Aggiornamento delle immagini delle app per patch o aggiornamenti di minore entità.

Scalabilità

• Scalare l'app (se applicabile).

Eliminazione

• Eliminazione dell'app in corso...
• Eliminazione di eventuali risorse che potrebbero essere intenzionalmente orfane, come PersistentVolumeClaims.