Requisiti per la pacchettizzazione della tua app

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

Il pacchetto dell'app è un pacchetto di immagini container e file di configurazione che vengono implementati nei cluster Kubernetes degli utenti. Per supportare il deployment dell'app in Google Kubernetes Engine dalla console Google Cloud, il pacchetto dell'app deve includere un contenitore di deployment. Il container di deployment esegue il push dei file di configurazione e della visualizzazione dei metadati nell'API Kubernetes.

Il pacchetto della tua 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 Anthos, 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 della tua 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 Google Click to Deploy Solutions. Il repository contiene pacchetti per le app open source più utilizzate, 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 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 tuo repository Git deve contenere un file LICENSE, che contiene la licenza open source per il repository.

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

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

  Consulta Requisiti per la configurazione.

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

• Se vuoi, 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), è necessario segnalarne l'utilizzo a Google in modo che i clienti vengano fatturati con precisione. Ti consigliamo di integrare la tua app con l'agente di fatturazione basato sull'utilizzo, che invia report sull'utilizzo a Google.

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

• Tutte le immagini container dell'app devono essere caricate nel registry in 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 la sezione Requisiti per la creazione di immagini delle app.

• Devi includere i test di integrazione per l'app.

  Vedi 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 utilizzarla.

  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, usa solo risorse beta o disponibili pubblicamente su Kubernetes.

• La tua configurazione deve eseguire il deployment di una risorsa personalizzata applicazione. La risorsa dell'applicazione contiene le informazioni che gli utenti vedono quando eseguono il deployment della loro applicazione tramite la UI di Cloud Marketplace.

  La risorsa dell'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 dell'applicazione e per esempi, consulta il repository GitHub applicazioni.

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

  È possibile sostituire i seguenti parametri:

  • 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 della tua app. Evita gli spazi dei nomi hardcoded nei tuoi 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 fai riferimento a un ServiceAccount in un RoleBinding. Eventuali riferimenti di questo tipo devono essere parametrizzati.

  • Nome app: il nome dell'istanza della risorsa dell'applicazione. Questa stringa deve essere inclusa nel nome di ciascuna risorsa dell'app, per evitare conflitti di nome 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 ignorarlo in modo che punti alle immagini pubblicate nel nostro Container Registry. Inoltre, i clienti possono sostituire facilmente le immagini modificate.

  • Secret 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 dei report sull'utilizzo, che la tua app utilizza per inviare i dati sull'utilizzo a Google.

    Scopri di più sui parametri di configurazione in 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 il tuo app sia compatibile con Istio, rivedi i limiti descritti in questa sezione. Per una panoramica di Istio, consulta la pagina 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. Questo 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 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 da Istio per abilitare l'accesso ai servizi esterni.

Ti consigliamo di configurare le connessioni in entrata utilizzando Istio Gateway, invece di LoadBalancer o delle risorse Ingress.

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

Per aiutare i tuoi clienti a configurare le comunicazioni tra i pod di app, ti consigliamo di aggiungere passaggi alle sezioni post-deployment della tua documentazione.

Requisiti per l'integrazione dell'agente di fatturazione

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

L'agente gestisce l'autenticazione e la generazione di report per l'endpoint di reporting 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 in base al quale generare report e le metriche di fatturazione per misurare l'utilizzo.

L'agente gestisce anche l'aggregazione locale, il ripristino in seguito a un arresto anomalo e nuovi tentativi. Per la metrica relativa all'ora di utilizzo, l'agente può essere configurato in modo da registrare automaticamente i battiti cardiaci.

L'agente espone anche lo stato dei report, consentendo all'app di rilevare se l'agente sta segnalando correttamente i dati di utilizzo.

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

Quando esegui l'integrazione con l'agente di fatturazione, valuta il comportamento della tua app quando i report sull'utilizzo non funzionano, il che potrebbe indicare uno dei seguenti casi:

• Il cliente ha annullato l'abbonamento.

• Il cliente potrebbe aver disattivato accidentalmente il canale di segnalazione. Ad esempio, i clienti potrebbero rimuovere inavvertitamente 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 ai clienti non viene addebitato alcun costo.

Integrazione dell'agente di fatturazione

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

Con il metodo sidecar, l'agente viene eseguito nel suo container, nello stesso pod Kubernetes del container dell'app. L'app comunica con l'interfaccia REST locale dell'agente.

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

In generale, l'approccio collaterale richiede meno sforzi di integrazione, mentre l'SDK è più robusto contro la disabilitazione accidentale.

Per la procedura dettagliata di integrazione, consulta il file README nel repository GitHub basato sull'utilizzo basato sull'utilizzo. Per un'implementazione di esempio, consulta i repository app e strumenti 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 si assicura 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 manifest di esempio che utilizza il secret del report, consulta la pagina di esempio di app WordPress in GitHub.

Il secret contiene i seguenti campi:

entitlement-id	Un identificatore che rappresenta il contratto del cliente per l'acquisto e l'utilizzo del software.
consumer-id	Un identificatore associato al diritto che viene passato 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 Service.

Se il tuo prodotto fornisce un componente SaaS oltre all'app, puoi facoltativamente controllare 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 di approvvigionamento, contatta il tuo Partner Engineer.

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

Requisiti per la creazione delle immagini container

L'app è composta da una o più immagini container. Inoltre, il tuo repository deve includere un container di deployment, che viene utilizzato quando i clienti eseguono il deployment dell'app dalla UI 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 per la creazione del Dockerfile e del container nel repository pubblico della tua app. La loro pubblicazione consente ai clienti di modificare o ricreare le immagini, che a volte sono necessarie per certificare le immagini per ambienti di produzione aziendali.

Se l'immagine dell'app dipende da un'immagine di base, come Debian, o 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 puoi garantire aggiornamenti tempestivi dell'immagine di base, in particolare per le patch di sicurezza.

Dopo aver creato le immagini dell'app, inviale al 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 trovarsi nella directory principale del repository. Ad esempio, se il repository di Container Registry è gcr.io/exampleproject/exampleapp, l'immagine dell'app dovrebbe essere in gcr.io/exampleproject/exampleapp.

• L'immagine per il 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 trovarsi in una propria cartella sotto l'immagine principale. Ad esempio, se l'app richiede un'immagine proxy, aggiungila a gcr.io/exampleproject/exampleapp/proxy.

• Tutte le immagini dell'app devono essere taggate con il gruppo release e la versione corrente. Ad esempio, se pubblichi la versione 2.0.5 nel canale di release 2.0, tutte le immagini devono avere i tag 2.0 e 2.0.5. Scopri come organizzare le release.

Ad esempio, nella seguente immagine viene mostrato il repository di Container Registry per l'app Kubernetes Grafana. Il percorso di rilascio è 5.3, mentre l'app contiene l'immagine principale dell'app, l'immagine del deployer in una propria cartella e l'immagine di Debian 9 in debian9. Tutte le immagini nel repository sono codificate con la stessa traccia, 5.3 e versione, in questa traccia, 5.3.4. Deve inoltre corrispondere al campo "Versione" della definizione della risorsa personalizzata (CRD) per la risorsa dell'applicazione come dichiarato nel deployment.

Il repository è in gcr.io/cloud-marketplace/google/grafana.

Utilizza gli ID immagine container selezionati in precedenza quando scegli gli ID prodotto.

Per caricare le immagini in Container Registry, taggale con il nome del Registro di sistema e poi esegui il push dell'immagine utilizzando gcloud. Ad esempio, usa 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 taggare e inviare 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 include la configurazione Kubernetes dell'app e gli strumenti client, come kubectl o Helm, che eseguono il push della configurazione all'API Kubernetes. In genere, il deployer utilizza lo stesso insieme di comandi a riga di comando che un utente potrebbe eseguire per eseguire il deployment dell'app.

Per creare il tuo 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, usa l'immagine kubectl base.
• Se usi un grafico Helm per la configurazione, usa l'immagine di base Helm.

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

Per i passaggi per creare l'immagine del deployer, consulta Creazione del deployer di applicazioni.

Parametri trasmessi alla tua app

Il tuo container di deployment deve dichiarare i parametri che devono essere raccolti dai clienti quando selezionano la tua app. Questi parametri vengono poi forniti al container del 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 elemento schema.yaml, consulta lo schema di deployment.

Richieste di cluster GPU

Se la tua app ha esigenze specifiche di GPU o richiede un utilizzo intensivo delle GPU, puoi specificare il tipo e il numero di GPU nel cluster utilizzando lo schema di deployment. Se specifichi le esigenze di GPU, la creazione di cluster assistiti è disabilitata.

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 vengono applicate e attese per essere integre.
• Test di funzionalità superati: il deployer avvia il pod del tester e osserva lo stato di uscita. Zero significa successo, non zero significa fallimento.
• Disinstallazione riuscita: l'app e tutte le sue risorse vengono rimosse dal cluster.

Per poter pubblicare un'app in Google Cloud Marketplace sono necessari risultati positivi.

Per maggiori dettagli su come pacchettizzare, eseguire e verificare questi test della funzionalità, segui 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 illustra le funzioni di base e le opzioni di configurazione. Questa sezione deve anche essere collegata 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) per consentire al cluster di gestire la risorsa Application.
• Se vendi un'app commerciale, i passaggi per acquisire e implementare un Secret della licenza da Cloud Marketplace.

Installazione

• Comandi per il deployment dell'app.
• Trasmettere i parametri disponibili nella configurazione dell'interfaccia utente.
• Blocco dei riferimenti alle immagini di digest immutabili.

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

  Scopri come aggiungere 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.
• Abilita il traffico in entrata e l'installazione dei certificati TLS (se applicabile).

Backup e ripristino

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

Aggiornamenti di immagini

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

Scalabilità

• Scalabilità dell'app (se applicabile).

Eliminazione

• Eliminazione dell'app in corso...
• Eseguire la pulizia di risorse che potrebbero essere orfane intenzionalmente, ad esempio PersistentVolumeClaim.