Requisiti per la creazione del pacchetto dell'app

Questa pagina descrive i requisiti per il packaging dell'app Kubernetes e le linee guida per soddisfarli.

Il pacchetto dell'app è un bundle di immagini container e file di configurazione che vengono distribuiti ai 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 dei metadati di visualizzazione nell'API Kubernetes.

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

• Scoprire la tua app nel catalogo di Cloud Marketplace
• Esegui il deployment dell'app nel cluster GKE o GKE Enterprise utilizzando 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 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 ed Elasticsearch.

Prima di iniziare

• Assicurati di aver configurato il tuo Google Cloud ambiente.
• Crea un repository Git pubblico per i file di configurazione, la guida per l'utente e altre risorse per eseguire l'app. Puoi ospitare il repository con un provider come GitHub, Cloud Source Repositories o sul tuo server. 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 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 di Kubernetes o un grafico Helm.

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

  Consulta i requisiti per la configurazione.

• La tua app deve essere eseguita su nodi che utilizzano un processore x86.

• Se vuoi che la tua app sia compatibile con Istio, esamina le limitazioni dei cluster che eseguono Istio.

• Se la tua app è commerciale (non BYOL), deve segnalare il suo utilizzo a Google, in modo che ai tuoi clienti venga addebitato l'importo corretto. Ti consigliamo di integrare la tua app con l'agente di fatturazione basata sull'utilizzo, che invia report sull'utilizzo a Google.

  Consulta Requisiti per integrare l'agente di fatturazione.

• Tutte le immagini container della tua app devono essere caricate nel tuo registro in Artifact Registry o Container Registry. Il registro deve includere anche un'immagine deployer, che esegue il push della configurazione dell'app nell'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 per l'utente con i passaggi per eseguire il deployment dell'app dalla riga di comando, configurarla e utilizzarla.

  Consulta 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 a livello generale.

• La configurazione deve eseguire il deployment di una risorsa personalizzata dell'applicazione. La risorsa Application contiene le informazioni che gli utenti vedono quando eseguono il deployment dell'app tramite la UI 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 sostituibili, tramite envsubst o come flag.

  I seguenti parametri devono poter essere sostituiti:

  • Spazio dei nomi: tutte le risorse della configurazione devono appartenere a un unico spazio dei nomi. Gli utenti di Cloud Marketplace configurano questo spazio dei nomi quando eseguono il deployment dell'app. Evita di codificare in modo permanente 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 ServiceAccount in un RoleBinding. 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 risorsa dell'app, per evitare conflitti di nomi se vengono implementate più istanze dell'app in un singolo spazio dei nomi.

  • Immagini container: ogni riferimento all'immagine, ad esempio in un PodSpec, deve essere sostituibile, in modo che Cloud Marketplace possa eseguirne l'override per puntare alle immagini pubblicate nel nostro Artifact Registry. Consente inoltre ai clienti di sostituire le immagini modificate.

  • Segreto della licenza: se la tua app esegue la misurazione commerciale, deve accettare il nome di una risorsa secret come parametro. Il secret contiene le credenziali per la generazione di 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 della riga di comando --client-only.

Limitazioni sui cluster con Istio

Se vuoi che la tua app sia compatibile con Istio, esamina le limitazioni descritte in questa sezione. Per una panoramica di Istio, vedi Che cos'è Istio?.

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

• Se i tuoi pod eseguono comandi kubectl che 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 di pacchetti del sistema operativo, potrebbero essere bloccate. I clienti devono configurare il traffico in uscita di Istio per attivare 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 tuo strumento di 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 dell'app, ti consigliamo di aggiungere 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 per l'endpoint di generazione di report sull'utilizzo di Google: Service Control. Dopo aver inviato il modello di prezzi, il team di Cloud Marketplace crea un servizio per la tua app da utilizzare come riferimento e le metriche di fatturazione per misurare l'utilizzo.

L'agente gestisce anche l'aggregazione locale, il ripristino in caso di arresto anomalo e i nuovi tentativi. Per la metrica ore di utilizzo, l'agente può essere configurato per segnalare automaticamente i battiti.

L'agente espone anche lo stato dei report, consentendo alla tua app di rilevare se l'agente segnala correttamente i dati di 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, considera il comportamento della tua app quando i report sull'utilizzo non vanno a buon fine, il che potrebbe indicare uno dei seguenti problemi:

• Il cliente ha annullato l'abbonamento.

• Il cliente potrebbe aver disattivato accidentalmente il canale di segnalazione. Ad esempio, i clienti potrebbero rimuovere o configurare in modo errato l'agente inavvertitamente 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 i dati di utilizzo e i clienti non vengono fatturati.

Integrazione dell'agente di fatturazione

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

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

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

In generale, l'approccio sidecar richiede meno sforzo di integrazione, mentre l'SDK è più robusto contro la disattivazione accidentale.

Per i passaggi di integrazione dettagliati, consulta il file README nel repository GitHub dell'agente di fatturazione basata sull'utilizzo. Per vedere un'implementazione di esempio, consulta i repository app e strumenti.

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 garantisce che esistano 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à dello schema REPORTING_SECRET.

Per un esempio di manifest che utilizza il secret di generazione dei report, consulta l'esempio di app WordPress su GitHub.

Il secret contiene i seguenti campi:

Se il tuo prodotto fornisce un componente SaaS oltre all'app, puoi facoltativamente fare in modo che questo componente SaaS controlli periodicamente la validità degli ID diritto utilizzando il servizio di approvvigionamento di Cloud Marketplace. Per ottenere l'accesso al servizio Procurement, contatta il tuo Partner Engineer.

Per informazioni sugli altri parametri trasmessi all'app, vedi 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 container dell'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 il Dockerfile e le istruzioni di build del container nel repository pubblico della tua app. La pubblicazione consente ai clienti di modificare o ricompilare 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, gli aggiornamenti dell'immagine di base vengono eseguiti tempestivamente, soprattutto per le patch di sicurezza.

Dopo aver creato le immagini dell'app, esegui il push nel registro 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 root del repository. Ad esempio, se il repository Artifact Registry o Container Registry è gcr.io/exampleproject/exampleapp, l'immagine dell'app deve trovarsi in gcr.io/exampleproject/exampleapp.

• L'immagine per il container di deployment deve trovarsi in una cartella denominata deployer. Nell'esempio riportato sopra, l'immagine di deployment deve trovarsi in gcr.io/exampleproject/exampleapp/deployer.

• Se la tua app utilizza immagini container aggiuntive, ogni immagine aggiuntiva deve trovarsi in una cartella separata 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 essere taggate con la traccia di rilascio e la versione corrente. Ad esempio, se rilasci la versione 2.0.5 sul canale di rilascio 2.0, tutte le immagini devono essere taggate con 2.0 e 2.0.5. Scopri di più sull'organizzazione delle uscite.

• Tutte le immagini della tua app devono contenere la seguente annotazione nel relativo manifest:

  com.googleapis.cloudmarketplace.product.service.name=services/SERVICE_NAME
  

  Sostituisci SERVICE_NAME con il nome del tuo servizio. Per trovare il nome del servizio, consulta la tabella dei prodotti nella pagina Panoramica di Producer Portal. Per maggiori informazioni sulle annotazioni, consulta la documentazione dell'Open Container Initiative relativa alle annotazioni su GitHub.

Ad esempio, l'immagine seguente mostra i repository Artifact Registry e Container Registry per l'app Kubernetes Grafana Cluster. La traccia di rilascio è 5.3 e l'app contiene l'immagine dell'app principale, l'immagine del deployer nella propria cartella e l'immagine Debian 9 in debian9. Tutte le immagini nel repository sono taggate con la stessa traccia, 5.3, e la stessa versione della traccia, 5.3.4. Deve corrispondere anche al campo "Version" della definizione di risorsa personalizzata (CRD) per la risorsa Application dichiarata nel programma di deployment.

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

Utilizza gli identificatori dell'immagine container che hai selezionato in precedenza quando scegli gli identificatori prodotto.

Per caricare le immagini in Artifact Registry o Container Registry, contrassegnale con il nome del registro, quindi 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 registro, consulta la documentazione pertinente per Artifact Registry o 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 contiene la configurazione Kubernetes della tua app e gli strumenti client, come kubectl o Helm, che inviano la configurazione all'API Kubernetes. In genere, il programma di deployment deve utilizzare lo stesso insieme di comandi della riga di comando che un utente eseguirebbe 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 kubectl per la configurazione, utilizza l'immagine di base di kubectl.
• 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 di riferimenti al proprietario, la generazione di password e la pulizia post-deployment.

Per i passaggi per creare l'immagine deployer, consulta Creazione del deployer dell'applicazione.

Parametri passati alla tua 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 container di deployment deve includere uno schema JSON, in formato YAML, nel seguente percorso: /data/schema.yaml.

Per scoprire come creare un schema.yaml, consulta Schema del programma di distribuzione.

Richieste di cluster GPU

Se la tua app ha esigenze specifiche di GPU o richiede un utilizzo intensivo della GPU, puoi specificare il tipo e il numero di GPU nel cluster utilizzando lo schema del deployer. Se specifichi le tue esigenze di GPU, la creazione assistita del cluster viene disattivata.

La tua app può 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 attese per diventare integre.
• I test di funzionalità vengono superati: il programma di deployment avvia il pod di test e ne monitora lo stato di uscita. Zero significa successo, un valore diverso da zero significa errore.
• Disinstallazione riuscita: l'app e tutte le relative risorse sono state rimosse correttamente dal cluster.

Per poter pubblicare un'app su Google Cloud Marketplace, è necessario ottenere risultati positivi.

Per informazioni dettagliate su come creare pacchetti, eseguire e verificare questi test di funzionalità, segui la documentazione sull'integrazione della verifica.

Requisiti per la guida per l'utente

La guida 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 collegarsi al prodotto pubblicato su Cloud Marketplace.

Configurazione unica

• Configurazione di strumenti client come kubectl o Helm, a seconda dei casi.
• Installazione della CustomResourceDefinition (CRD) dell'applicazione, in modo che il 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.
• Trasmissione dei parametri disponibili nella configurazione della UI.
• Blocco dei riferimenti alle immagini sui digest immutabili.

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

  Scopri di più sull'aggiunta di campi di input al deployer

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 dell'ingresso e installazione dei certificati TLS (Transport Layer Security), se applicabile.

  Scopri di più sull'attivazione dell'ingresso e sull'installazione dei certificati TLS

Backup e ripristino

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

Aggiornamenti di immagini

• Aggiornamento delle immagini dell'app per patch o aggiornamenti secondari.

Scalabilità

• Scalabilità dell'app (se applicabile).

Eliminazione

• Eliminazione dell'app.
• Pulizia di tutte le risorse che potrebbero essere orfane intenzionalmente, ad esempio PersistentVolumeClaims.