Questa pagina descrive i requisiti per il packaging dell'app Kubernetes e le linee guida per soddisfarli.
Il pacchetto dell'app è un insieme di immagini container e file di configurazione che vengono distribuiti 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 contenitore di deployment. Il contenitore di deployment spinge i file di configurazione e mostra i metadati all'API Kubernetes.
Il pacchetto dell'app consente agli utenti di Google Cloud di:
- Trovare la tua app nel catalogo di Cloud Marketplace
- Eseguire il deployment dell'app nel cluster GKE o GKE Enterprise utilizzando la console Google Cloud
- Interagire 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 di app, consulta il repository GitHub per le soluzioni Google Click to Deploy. Il repository contiene pacchetti per app open source di uso comune, come WordPress e Elasticsearch.
Prima di iniziare
- Assicurati di avere configurato il tuo ambiente Google Cloud.
- Crea un repository Git pubblico per i file di configurazione, la guida utente e altre risorse per eseguire l'app. Puoi ospitare il repository con un fornitore come GitHub, Cloud Source Repositories o sul tuo server. Ti consigliamo un repository dedicato per ogni prodotto che distribuisci.
Panoramica
L'app deve soddisfare i seguenti requisiti:
Il repository Git deve contenere un file LICENSE, che contiene la licenza open source del 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 di Kubernetes o un grafico Helm.
La configurazione deve includere una risorsa personalizzata Application, che descrive l'app.
Consulta la sezione Requisiti per la configurazione.
L'app deve essere eseguita su nodi che utilizzano un processore x86.
Se vuoi che la tua app sia compatibile con Istio, esamina facoltativamente le limitazioni dei cluster che eseguono Istio.
Se la tua app è commerciale (non BYOL), deve segnalare il proprio utilizzo a Google, in modo che la fatturazione ai clienti sia accurata. Ti consigliamo di integrare la tua app con l'agente di fatturazione in base all'utilizzo, che invia i report sull'utilizzo a Google.
Consulta i requisiti per integrare l'agente di fatturazione.
Tutte le immagini container dell'app devono essere caricate nel registro in Artifact Registry o Container Registry. Il registry deve includere anche un'immagine di deployer, che spinge la 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 dell'app.
Devi includere i test di integrazione per l'app.
Consulta i Requisiti per la procedura di verifica.
Devi includere una guida utente con i passaggi per eseguire il deployment dell'app dalla riga di comando, configurarla e utilizzarla.
Consulta i requisiti per la guida dell'utente.
Requisiti per la configurazione
Puoi fornire la 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 beta o disponibili in generale.
La configurazione deve eseguire il deployment di una risorsa personalizzata dell'applicazione. La risorsa Application contiene le informazioni visualizzate dagli utenti quando eseguono il deployment dell'app tramite l'interfaccia utente di Cloud Marketplace.
La risorsa Application è 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 Application e per esempi, consulta il repository GitHub dell'applicazione.
La configurazione deve utilizzare parametri che possono essere sostituiti utilizzando
envsubsto come flag.I seguenti parametri devono essere sostituibili:
Spazio dei nomi: tutte le risorse della 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 di codificare in modo rigido gli spazi dei nomi nei manifest, in modo che le risorse specificate vengano create nello spazio dei nomi selezionato dagli utenti. A volte gli spazi dei nomi vengono visualizzati anche all'interno delle definizioni delle risorse, ad esempio quando si fa riferimento a un
ServiceAccountin unRoleBinding. Qualsiasi riferimento di questo tipo deve essere parametrizzato.Nome app: il nome dell'istanza della risorsa Application. Questa stringa deve essere inclusa nel nome di ciascuna delle risorse dell'app, per evitare collisioni di nomi se vengono implementate più istanze dell'app in un unico spazio dei nomi.
Immagini container: ogni riferimento all'immagine, ad esempio in un
PodSpec, deve essere sostituibile, in modo che Cloud Marketplace possa sostituirli per indirizzare le immagini pubblicate nel nostro Artifact Registry. Inoltre, consente ai clienti di sostituire le immagini modificate.Secret della licenza: se la tua app esegue la misurazione per scopi commerciali, deve accettare il nome di una risorsa Secret come parametro. Il segreto contiene le credenziali per i report sull'utilizzo, che la tua app utilizza per inviare i 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
--client-onlydella riga di comando.
Limitazioni dei cluster con Istio
Se vuoi che il tuo AP sia compatibile con Istio, esamina le limitazioni descritte in questa sezione. Per una panoramica di Istio, consulta Che cos'è Istio?.
Se i tuoi clienti eseguono Istio nei loro cluster, per impostazione predefinita Istio controlla il traffico di rete tra i pod della tua app. Ciò potrebbe bloccare la comunicazione di rete nei seguenti scenari:
Se i pod eseguono comandi
kubectlche utilizzano l'indirizzo IP del cluster, i comandi potrebbero non riuscire.Se la tua app utilizza la comunicazione pod-to-pod o basata su IP, il passaggio di formazione del cluster potrebbe non riuscire.
Le connessioni esterne a servizi di terze parti, come i repository dei pacchetti del sistema operativo, potrebbero essere bloccate. I clienti devono configurare il traffico in uscita di Istio per consentire l'accesso ai servizi esterni.
Ti consigliamo di configurare le connessioni in entrata utilizzando Istio Gateway anziché le risorse LoadBalancer o Ingress.
Se utilizzi Helm per la configurazione, utilizza la proprietà x-google-marketplace ISTIO_ENABLED nello schema per l'immagine di deployment. Se questa proprietà è true, il deployer deve modificare il deployment, ad esempio attendere che il sidecar Istio sia pronto.
Per aiutare i tuoi clienti a configurare la comunicazione tra i pod di app, ti consigliamo di aggiungere passaggi alle sezioni di 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 i report all'endpoint per i report sull'utilizzo di Google: Controllo servizi. Dopo aver inviato il modello di prezzo, il team di Cloud Marketplace crea un servizio per la tua app e le metriche di fatturazione per misurare l'utilizzo.
L'agente gestisce anche l'aggregazione locale, il recupero in caso di arresto anomalo e i nuovi tentativi. Per la metrica ore di utilizzo, l'agente può essere configurato per segnalare automaticamente i heartbeat.
L'agente espone anche lo stato dei report, consentendo alla tua app di rilevare se l'agente sta registrando correttamente i dati di utilizzo.
I clienti acquistano l'app in Cloud Marketplace per ottenere una licenza, che viene collegata all'app al momento del deployment.
Quando esegui l'integrazione con l'agente di fatturazione, tieni presente il comportamento della tua app quando i report sull'utilizzo non vanno a buon fine, il che potrebbe indicare una delle seguenti situazioni:
Il cliente ha annullato l'abbonamento.
Il cliente potrebbe aver disattivato accidentalmente il canale di segnalazione. Ad esempio, i clienti potrebbero rimuovere o configurare erroneamente l'agente o la rete potrebbe impedire all'agente di accedere all'endpoint di generazione di report di Google.
Segui le best practice per segnalare l'utilizzo e gestire i casi in cui Google non riceve i dati sull'utilizzo e la fatturazione ai clienti non viene eseguita.
Integrazione dell'agente di fatturazione
Puoi integrare l'agente come contenitore sidecar, che viene eseguito nello stesso pod della tua app, o 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 file binario dell'app. L'SDK è implementato in modo nativo per Go, con associazioni per Python.
In generale, l'approccio sidecar richiede meno impegno di integrazione, mentre l'SDK è più resistente alla disattivazione accidentale.
Per la procedura dettagliata di integrazione, consulta il file README nel repository GitHub dell'agente di fatturazione basata sull'utilizzo. Per vedere un'implementazione di esempio, consulta i repository dell'app e degli strumenti di esempio.
Credenziali per segnalare l'utilizzo
L'agente di fatturazione richiede credenziali che gli consentano di inviare i report sull'utilizzo a Google. Cloud Marketplace genera queste credenziali quando gli utenti eseguono il deployment
dell'app da Cloud Marketplace e garantisce che esistano come Secret
nel namespace Kubernetes di destinazione prima del deployment dell'app.
Il nome di questo secret viene passato all'app come proprietà dello schema REPORTING_SECRET.
Per un manifest di esempio che utilizza il secret per i report, consulta l'esempio di app WordPress su GitHub.
Il segreto contiene i seguenti campi:
|
Un identificatore che rappresenta l'accettazione da parte del cliente di acquistare e utilizzare il software. |
|
Un identificatore associato al diritto che viene passato a Google Service Control insieme ai report sull'utilizzo. |
|
La chiave JSON dell'account di servizio Google Cloud utilizzata per autenticarsi a Google Service Control. |
Se il tuo prodotto fornisce un componente SaaS oltre all'app, puoi scegliere di verificare periodicamente la validità degli ID diritto tramite il servizio di approvvigionamento di Cloud Marketplace. Per ottenere l'accesso al servizio di approvvigionamento, contatta il tuo Partner Engineer.
Per informazioni sugli altri parametri trasmessi all'app, consulta Parametri trasmessi all'app più avanti in questa sezione.
Requisiti per la creazione delle immagini container
La tua app è costituita da una o più immagini di contenitori per app. Inoltre, il repository deve includere un contenitore di deployment, che viene utilizzato quando i clienti eseguono il deployment dell'app dall'interfaccia utente di Cloud Marketplace.
Le immagini container vengono generalmente create utilizzando un
Dockerfile e lo strumento a riga di comando docker
build. Ti consigliamo di pubblicare il Dockerfile e le istruzioni di compilazione del container nel repository pubblico della tua app. La loro pubblicazione consente ai clienti di modificare o ricostruire le immagini, il che a volte è necessario per certificare le immagini per gli ambienti di produzione aziendali.
Se l'immagine dell'app dipende da un'immagine di base, come Debian, o da un'immagine di runtime del linguaggio, come Python o OpenJDK, ti consigliamo vivamente di utilizzare una delle immagini container certificate di Cloud Marketplace. In questo modo, avrai aggiornamenti tempestivi dell'immagine di base, in particolare per i patch di sicurezza.
Dopo aver creato le immagini dell'app, esegui il push nel registry di staging che hai creato in Artifact Registry o Container Registry quando hai configurato l'ambiente.
Il repository Artifact Registry o Container Registry deve avere la seguente struttura:
L'immagine principale dell'app deve trovarsi nella directory principale del repository. Ad esempio, se il tuo repository Artifact Registry o Container Registry è
gcr.io/exampleproject/exampleapp, l'immagine dell'app deve trovarsi ingcr.io/exampleproject/exampleapp.L'immagine del contenitore di deployment deve trovarsi in una cartella denominata
deployer. Nell'esempio riportato sopra, l'immagine di deployment deve essere ingcr.io/exampleproject/exampleapp/deployer.Se la tua app utilizza immagini contenitore aggiuntive, ogni immagine aggiuntiva deve trovarsi nella propria cartella sotto l'immagine principale. Ad esempio, se la tua app richiede un'immagine
proxy, aggiungila agcr.io/exampleproject/exampleapp/proxy.Tutte le immagini dell'app devono essere contrassegnate con il canale di rilascio e la versione corrente. Ad esempio, se stai rilasciando la versione
2.0.5nel canale di rilascio2.0, tutte le immagini devono essere taggate con2.0e2.0.5. Scopri come organizzare le uscite.
Ad esempio, l'immagine seguente mostra i repository Artifact Registry e Container Registry per l'app Kubernetes Grafana Cluster. Il canale di rilascio è 5.3 e l'app contiene l'immagine dell'app principale, l'immagine del deployer nella relativa cartella e l'immagine Debian 9 in debian9. Tutte le immagini nel repository sono taggate con lo stesso canale,
5.3, e la stessa versione del canale, 5.3.4. Deve inoltre corrispondere al
campo "Version" della definizione della risorsa personalizzata (CRD) per la risorsa applicazione come dichiarato nel deployer.
Il repository si trova all'indirizzo gcr.io/cloud-marketplace/google/grafana.
Utilizza gli identificatori delle immagini del contenitore che hai selezionato in precedenza quando scegli gli identificatori dei prodotti.
Per caricare le immagini in Artifact Registry o Container Registry, contrassegnale con il nome del registry 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 per taggare ed eseguire il push delle immagini nel tuo registry, consulta la documentazione pertinente per Artifact Registry o la documentazione di Container Registry.
Requisiti per il contenitore di deployment
Il contenitore di deployment o deployer viene utilizzato quando i clienti eseguono il deployment del tuo prodotto da Cloud Marketplace. L'immagine del deployer impacchetta la configurazione Kubernetes della tua app e gli strumenti client, come kubectl o Helm, che trasferiscono la configurazione all'API Kubernetes. In genere, il programma di deployment deve utilizzare lo stesso insieme di comandi da riga di comando che un utente eseguirà per eseguire il deployment dell'app.
Per creare il deployer, utilizza una delle immagini di base per i container di deployment dalla directory del marketplace del repository degli strumenti:
- Se utilizzi
kubectlper la configurazione, utilizza l'immagine di base kubectl. - Se utilizzi un grafico Helm per la tua configurazione, utilizza l'immagine di base Helm.
Le immagini di base hanno utilità integrate per attività come l'assegnazione dei riferimenti del proprietario, la generazione di password e la pulizia post-deployment.
Per la procedura di creazione dell'immagine del deployer, consulta Creazione del deployer dell'applicazione.
Parametri passati all'app
Il contenitore di deployment deve dichiarare i parametri che devono essere raccolti dai clienti quando selezionano la tua app. Questi parametri vengono poi forniti al contenitore di deployment quando gli utenti eseguono il deployment dell'app.
Per configurare questi parametri, l'immagine del contenitore di deployment deve includere un
schema JSON, in formato YAML, al seguente
percorso: /data/schema.yaml.
Per scoprire come creare un schema.yaml, consulta lo schema del programma di deployment.
Richieste di cluster GPU
Se la tua app ha esigenze specifiche per le GPU o è intensiva per le GPU, puoi specificare il tipo e il numero di GPU nel cluster utilizzando lo schema del deployer. Se specifichi le tue esigenze in termini di GPU, la creazione di cluster assistita viene disattivata.
L'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:
- L'installazione è riuscita: tutte le risorse sono state applicate e si è aspettato che diventino in buono stato.
- I test di funzionalità superati: il deployer avvia il pod di tester e ne controlla lo stato di uscita. Zero significa successo, diverso da zero significa errore.
- La disinstallazione è riuscita: l'app e tutte le relative risorse sono state rimosse correttamente dal cluster.
Per poter pubblicare un'app su Google Cloud Marketplace, sono necessari risultati positivi.
Per informazioni dettagliate su come pacchettizzare, eseguire e verificare questi test di funzionalità, consulta la documentazione sull'integrazione della verifica.
Requisiti per la guida dell'utente
La guida dell'utente deve includere le seguenti informazioni:
Panoramica
- Una panoramica generale dell'app, che copre le funzioni di base e le opzioni di configurazione. Questa sezione deve anche includere un link al prodotto pubblicato su Cloud Marketplace.
Configurazione una tantum
- Configurazione di strumenti client come
kubectlo Helm, a seconda dei casi. - Installa la risorsa CustomResourceDefinition (CRD) Application in modo che il tuo cluster possa gestire la risorsa Application.
- Se vendi un'app commerciale, segui i passaggi per acquisire ed eseguire il deployment di un secret di licenza da Cloud Marketplace.
Installazione
- Comandi per il deployment dell'app.
- Parametri di passaggio disponibili nella configurazione dell'interfaccia utente.
- Bloccare i riferimenti alle immagini in digest immutabili.
Se aggiungi campi di immissione personalizzati allo schema del programma di deployment, aggiungi informazioni sui valori previsti, se applicabili.
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).
- Modificare nomi utente e password.
- Attivare l'ingresso e installare i certificati TLS (se applicabili).
Backup e ripristino
- Eseguire il backup dello stato dell'app.
- Ripristino dello stato dell'app da un backup.
Aggiornamenti delle immagini
- Aggiornamento delle immagini dell'app per patch o aggiornamenti minori.
Scalabilità
- Scalabilità dell'app (se applicabile).
Eliminazione
- Eliminazione dell'app.
- Eliminazione di eventuali risorse che potrebbero essere intenzionalmente orfane, come PersistentVolumeClaims.