Informazioni sui target personalizzati

Questo documento descrive il funzionamento delle destinazioni personalizzate in Cloud Deploy.

Cloud Deploy include il supporto integrato per vari ambienti di runtime come target. Tuttavia, l'elenco dei tipi di target supportati è limitato. Con i target personalizzati, puoi eseguire il deployment in altri sistemi oltre ai runtime supportati.

Un target personalizzato è una destinazione che rappresenta un ambiente di output arbitrario diverso da un runtime supportato da Cloud Deploy.

La pagina Creare un target personalizzato descrive la procedura per definire un tipo di target personalizzato e implementarlo come target in una pipeline di distribuzione.

Che cosa viene inserito in un target personalizzato?

Ogni target personalizzato è costituito dai seguenti componenti:

  • Azioni personalizzate, definite in skaffold.yaml

    Sono simili alla definizione degli hook di deployment. Nel skaffold.yaml file, definisci customActions, dove ogni azione personalizzata identifica un'immagine container da utilizzare e i comandi da eseguire su quel container.

    In questo modo, il target personalizzato è semplicemente un'azione o un insieme di azioni personalizzate.

    Per qualsiasi tipo di target personalizzato, devi configurare un'azione di rendering personalizzata e un'azione di deployment personalizzata. Queste azioni utilizzano i valori forniti da Cloud Deploy e devono soddisfare un insieme di output richiesti.

    L'azione di rendering personalizzato è facoltativa, ma devi crearne una, a meno che il tuo target personalizzato non funzioni correttamente se visualizzato da skaffold render, che è il valore predefinito per Cloud Deploy.

  • Una definizione del tipo di target personalizzato

    CustomTargetType è una risorsa Cloud Deploy che identifica le azioni personalizzate (definite separatamente in skaffold.yaml) che i target di questo tipo utilizzano per le attività di rendering della release e di deployment dell'implementazione.

  • Una definizione del target

    La definizione di un target personalizzato è la stessa di qualsiasi tipo di target, tranne per il fatto che include la proprietà customTarget, il cui valore è il nome del CustomTargetType.

Una volta installati questi componenti, puoi utilizzare il target come qualsiasi altro, facendovi riferimento dalla progressione della pipeline di distribuzione e sfruttando al meglio le funzionalità di Cloud Deploy, come promozione e approvazioni e rollback.

Un esempio

La guida rapida Definire e utilizzare un tipo di target personalizzato crea un tipo di target personalizzato che include comandi semplici da eseguire su un'immagine contenitore: un comando per il rendering e uno per il deployment. I comandi, in questo caso, aggiungono semplicemente del testo ai file di output richiesti per il rendering e il deployment.

Per altri esempi, consulta la sezione Esempi di target personalizzati.

Input e output obbligatori

Qualsiasi tipo di target personalizzato definito per Cloud Deploy deve soddisfare i requisiti per input e output, sia per il rendering sia per il deployment. Questa sezione elenca gli input e le uscite richiesti e come vengono forniti.

Cloud Deploy fornisce gli input richiesti, sia per il rendering sia per il deployment, come variabili di ambiente. Le sezioni seguenti elencano questi input, nonché gli output che le azioni di rendering e di implementazione personalizzate devono restituire.

Esegui il deployment dei parametri come variabili di ambiente

Oltre alle variabili di ambiente elencate in questa sezione, Cloud Deploy può passare ai container personalizzati tutti i parametri di deployment che hai impostato.

Scopri di più.

Input per il rendering delle azioni

Per le azioni di rendering personalizzate, Cloud Deploy fornisce i seguenti input obbligatori come variabili di ambiente. Per le implementazioni in più fasi (deployment canary), Cloud Deploy fornisce queste variabili per ogni fase.

  • CLOUD_DEPLOY_PROJECT

    Il progetto Google Cloud in cui viene creato il tipo di target personalizzato.

  • CLOUD_DEPLOY_LOCATION

    La regione Google Cloud per il tipo di target personalizzato.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Il nome della pipeline di distribuzione Cloud Deploy che fa riferimento al tipo di target personalizzato.

  • CLOUD_DEPLOY_RELEASE

    Il nome della release per la quale viene invocata l'operazione di rendering.

  • CLOUD_DEPLOY_TARGET

    Il nome del target Cloud Deploy che utilizza il tipo di target personalizzato.

  • CLOUD_DEPLOY_PHASE

    La fase di implementazione a cui corrisponde il rendering.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Per l'azione di rendering personalizzata, il valore è sempre RENDER.

  • CLOUD_DEPLOY_FEATURES

    Un elenco separato da virgole delle funzionalità di Cloud Deploy che il contenitore personalizzato deve supportare. Questa variabile viene compilata in base alle funzionalità configurate nella pipeline di importazione.

    Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo di interrompere il rendering.

    Per i deployment standard, questo valore è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornito da Cloud Deploy è CANARY, l'azione di rendering viene invocata per ogni fase del canary. La percentuale di canary per ogni fase è fornita nella variabile di ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    La percentuale di deployment associata a questa operazione di rendering. Se la variabile di ambiente CLOUD_DEPLOY_FEATURES è impostata su CANARY, l'azione di rendering personalizzata viene chiamata per ogni fase e questa variabile è impostata sulla percentuale di canary per ogni fase. Per i deployment standard e per i deployment canary che hanno raggiunto la fase stable, il valore è 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Il fornitore di spazio di archiviazione. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Il percorso di Cloud Storage per l'archivio dei file di rendering scritto al momento della creazione della release.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Il percorso Cloud Storage in cui il contenitore di rendering personalizzato deve caricare gli elementi da utilizzare per il deployment. Tieni presente che l'azione di rendering deve caricare un file denominato results.json contenente i risultati di questa operazione di rendering. Per ulteriori informazioni, consulta la sezione Output dell'azione di rendering.

Output dell'azione di rendering

L'azione di rendering personalizzata deve fornire le informazioni descritte in questa sezione. Le informazioni devono essere incluse nel file dei risultati, denominato results.json, che si trova nel bucket Cloud Storage fornito da Cloud Deploy.

  • File di configurazione o file di configurazione visualizzati

  • Un file results.json contenente le seguenti informazioni:

    • Un'indicazione dello stato di esito positivo o negativo dell'azione personalizzata.

      I valori validi sono SUCCEEDED e FAILED.

    • (Facoltativo) Eventuali messaggi di errore generati dall'azione personalizzata.

    • Il percorso di Cloud Storage per il file o i file di configurazione visualizzati.

      Il percorso di tutti i file di configurazione visualizzati è l'URI completo. Puoi completarlo in parte utilizzando il valore di CLOUD_DEPLOY_OUTPUT_GCS_PATH fornito da Cloud Deploy.

      Devi fornire il file di configurazione visualizzato, anche se vuoto. I contenuti del file possono essere qualsiasi cosa, in qualsiasi formato, purché sia utilizzabile dall'azione di deployment personalizzata. Ti consigliamo di creare un file facilmente leggibile, in modo che tu e gli altri utenti della tua organizzazione possiate visualizzarlo nell'inspector delle release.

    • (Facoltativo) una mappa di tutti i metadati che vuoi includere

      Il target personalizzato crea questi metadati. Questi metadati vengono archiviati nella release, nel campo custom_metadata.

Se devi esaminare il file results.json, ad esempio per il debug, puoi trovare l'URI Cloud Storage nei log di Cloud Build.

File di risultati di rendering di esempio

Di seguito è riportato un esempio di output del file results.json di un'azione di rendering personalizzata:

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Input per le azioni di deployment

Per le azioni di deployment personalizzate, Cloud Deploy fornisce i seguenti input obbligatori come variabili di ambiente:

  • CLOUD_DEPLOY_PROJECT

    Il progetto Google Cloud in cui viene creato il target personalizzato.

  • CLOUD_DEPLOY_LOCATION

    La regione Google Cloud per il tipo di target personalizzato.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    Il nome della pipeline di distribuzione Cloud Deploy che fa riferimento al target che utilizza il tipo di target personalizzato.

  • CLOUD_DEPLOY_RELEASE

    Il nome della release per cui viene invocata l'operazione di deployment.

  • CLOUD_DEPLOY_ROLLOUT

    Il nome dell'implementazione Cloud Deploy a cui si riferisce questo deployment.

  • CLOUD_DEPLOY_TARGET

    Il nome del target Cloud Deploy che utilizza il tipo di target personalizzato.

  • CLOUD_DEPLOY_PHASE

    La fase di implementazione a cui corrisponde il deployment.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Per l'azione di deployment personalizzato, il valore è sempre DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Un elenco separato da virgole delle funzionalità di Cloud Deploy che il contenitore personalizzato deve supportare. Questa variabile viene compilata in base alle funzionalità configurate nella pipeline di importazione.

    Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo di interrompere il rendering.

    Per i deployment standard, questo valore è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornito da Cloud Deploy è CANARY, l'azione di rendering viene invocata per ogni fase del canary. La percentuale di canary per ogni fase è fornita nella variabile di ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    La percentuale di deployment associata a questa operazione di deployment. Se la variabile di ambiente CLOUD_DEPLOY_FEATURES è impostata su CANARY, l'azione di deployment personalizzata viene chiamata per ogni fase e questa variabile è impostata sulla percentuale di canary per ogni fase. L'azione di deployment deve essere eseguita per ogni fase.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Il fornitore di spazio di archiviazione. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Il percorso di Cloud Storage in cui il visualizzatore personalizzato ha scritto i file di configurazione visualizzati.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Il percorso di Cloud Storage alla configurazione Skaffold visualizzata.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Il percorso Cloud Storage del file manifest visualizzato.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Il percorso della directory Cloud Storage in cui il container di deployment personalizzato dovrebbe caricare gli artefatti di deployment. Per ulteriori informazioni, consulta la sezione Output dell'azione di deployment.

Output dell'azione di deployment

L'azione di deployment personalizzata deve scrivere un file di output results.json. Questo file deve trovarsi nel bucket Cloud Storage fornito da Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

Il file deve includere quanto segue:

  • Un'indicazione dello stato di esito positivo o negativo dell'azione di deployment personalizzato.

    Di seguito sono riportati gli stati validi:

  • (Facoltativo) un elenco di file di artefatti di deployment, sotto forma di percorsi Cloud Storage

    Il percorso è l'URI completo. Puoi compilarlo in parte utilizzando il valore del CLOUD_DEPLOY_OUTPUT_GCS_PATH fornito da Cloud Deploy.

    I file elencati qui vengono compilati nelle risorse di esecuzione dei job come artefatti di deployment.

  • (Facoltativo) un messaggio di errore, se l'azione di deployment personalizzato non va a buon fine (restituisce uno stato FAILED)

    Questo messaggio viene utilizzato per compilare failure_message nella esecuzione del job per questa azione di deployment.

  • (Facoltativo) un messaggio di salto per fornire informazioni aggiuntive se l'azione restituisce uno stato SKIPPED.

  • (Facoltativo) una mappa di tutti i metadati che vuoi includere

    Il target personalizzato crea questi metadati. Questi metadati vengono memorizzati nella esecuzione del job e nell'implementazione, nel campo custom_metadata.

Se devi esaminare il file results.json, ad esempio per il debug, puoi trovare l'URI Cloud Storage nei log di rendering della release di Cloud Build.

File di risultati di deployment di esempio

Di seguito è riportato un esempio di output del file results.json di un'azione di deployment personalizzata:

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

Ulteriori informazioni sulle azioni personalizzate

Di seguito sono riportati alcuni aspetti da tenere presenti durante la configurazione e l'utilizzo dei tipi di target personalizzati.

Esecuzione delle azioni personalizzate

Le azioni di rendering e deployment personalizzate vengono eseguite nell'ambiente di esecuzione Cloud Deploy. Non puoi configurare le tue azioni personalizzate in modo che vengano eseguite su un cluster Google Kubernetes Engine.

Utilizzo di configurazioni Skaffold remote e riutilizzabili

Come descritto in questo documento, configura l'azione personalizzata nel skaffold.yaml file fornito durante la creazione della release. Tuttavia, puoi anche archiviare le configurazioni Skaffold in un repository Git o in un bucket Cloud Storage e farvi riferimento dalla definizione del tipo di destinazione personalizzato. In questo modo, puoi utilizzare le azioni personalizzate definite e archiviate in un'unica posizione condivisa, anziché includerle nel file skaffold.yaml di ogni release.

Target personalizzati e strategie di implementazione

I target personalizzati sono completamente supportati per i deployment standard.

Cloud Deploy supporta i deployment canary, a condizione che il renderizzatore e il deployer personalizzati supportino la funzionalità canary.

Devi utilizzare la configurazione canary personalizzata. I canari automatici e personalizzati non sono supportati.

Target e parametri di deployment personalizzati

Puoi utilizzare i parametri di implementazione con i target personalizzati. Puoi impostarli nella fase della pipeline di importazione, nel target che utilizza un tipo di target personalizzato o nella release.

I parametri di deployment vengono passati ai contenitori di rendering e deployment personalizzati come variabili di ambiente, oltre a quelle già fornite.

Esempi di target personalizzati

Il repository cloud-deploy-samples contiene un insieme di implementazioni di target personalizzati di esempio. Sono disponibili i seguenti sample:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Ogni esempio include una guida rapida.

Questi esempi non sono un prodotto Google Cloud supportato e non sono coperti da un contratto di assistenza Google Cloud. Per segnalare bug o richiedere funzionalità in un prodotto Google Cloud, contatta l'assistenza Google Cloud.

Passaggi successivi