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 è finito. Con le destinazioni personalizzate, puoi eseguire il deployment su altri sistemi oltre ai runtime supportati.

Una destinazione personalizzata è una destinazione che rappresenta un ambiente di output arbitrario diverso da un runtime supportato da Cloud Deploy.

La pagina Crea un target personalizzato descrive il processo di definizione di un tipo di target personalizzato e la sua implementazione come target in una pipeline di distribuzione.

Cosa include un target personalizzato?

Ogni target personalizzato è costituito dai seguenti componenti:

  • Attività, che definiscono come eseguire il rendering e il deployment per il tuo tipo di target personalizzato

    Le implementazioni del rendering personalizzato e del deployment personalizzato utilizzano i valori forniti da Cloud Deploy e devono soddisfare un insieme di output richiesti.

    Il rendering personalizzato è facoltativo, ma devi crearne uno a meno che la tua destinazione personalizzata non funzioni correttamente se viene eseguito il rendering con i renderer integrati di Cloud Deploy.

  • Una definizione del tipo di target personalizzato

    CustomTargetType è una risorsa Cloud Deploy che identifica le attività che i target di questo tipo utilizzano per il rendering della release e le attività di deployment del rollout.

  • Una definizione del target

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

Con questi componenti, puoi utilizzare il target come faresti con qualsiasi altro target, facendo riferimento alla progressione della pipeline di distribuzione e sfruttando appieno le funzionalità di Cloud Deploy, come promozione e approvazioni e rollback.

Esempio

La guida rapida Definisci e utilizza un tipo di target personalizzato crea un tipo di target personalizzato che include comandi da eseguire su un'immagine container: un comando per il rendering e uno per il deployment. I comandi, in questo caso, aggiungono solo testo ai file di output richiesti per il rendering e il deployment.

Per altri esempi, consulta Esempi di target personalizzati.

Input e output richiesti

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

Cloud Deploy fornisce gli input richiesti, sia per il rendering che per il deployment, come variabili di ambiente. Le sezioni seguenti elencano questi input, nonché gli output che il rendering e il deployment personalizzati 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 tuoi container personalizzati qualsiasi parametro di deployment che hai impostato.

Scopri di più.

Input per i rendering personalizzati

Per i rendering personalizzati, Cloud Deploy fornisce i seguenti input come variabili di ambiente. Per i rollout in più fasi (deployment canary), Cloud Deploy fornisce queste variabili per ogni fase.

  • CLOUD_DEPLOY_PROJECT

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

  • CLOUD_DEPLOY_PROJECT_ID

    L'ID progetto Google Cloud del progetto.

  • CLOUD_DEPLOY_LOCATION

    La Google Cloud regione per il tipo di target personalizzato.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

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

  • CLOUD_DEPLOY_RELEASE

    Il nome della release per cui viene richiamata 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 il rendering personalizzato, questo valore è sempre RENDER.

  • CLOUD_DEPLOY_FEATURES

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

    Se la tua implementazione non supporta le funzionalità di questo elenco, ti consigliamo che non funzioni durante il rendering.

    Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornito da Cloud Deploy è CANARY, il rendering viene richiamato 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, viene chiamato il rendering personalizzato per ogni fase e questa variabile è impostata sulla percentuale canary per ogni fase. Per i deployment standard e per i deployment canary che hanno raggiunto la fase stable, questo valore è 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Il fornitore di spazio di archiviazione. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Il percorso Cloud Storage dell'archivio del file di rendering scritto al momento della creazione della release.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Il percorso Cloud Storage in cui è previsto il caricamento degli artefatti da utilizzare per il deployment nel container di rendering personalizzato. Tieni presente che il rendering deve caricare un file denominato results.json contenente i risultati di questa operazione di rendering. Per saperne di più, consulta Output del rendering personalizzato.

Output dal rendering personalizzato

Il rendering personalizzato 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 (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

  • File o file di configurazione sottoposti a rendering

  • Un file results.json contenente le seguenti informazioni:

    • Un'indicazione dello stato di esito positivo o negativo del rendering personalizzato.

      I valori validi sono SUCCEEDED e FAILED.

    • (Facoltativo) eventuali messaggi di errore generati dal rendering personalizzato.

    • Il percorso Cloud Storage per il file di configurazione o i file sottoposti a rendering.

      Il percorso di tutti i file di configurazione sottoposti a rendering è l'URI completo. Lo compili in parte utilizzando il valore di CLOUD_DEPLOY_OUTPUT_GCS_PATH fornito da Cloud Deploy.

      Devi fornire il file di configurazione sottoposto a rendering, anche se è vuoto. Il contenuto del file può essere qualsiasi cosa, in qualsiasi formato, purché sia utilizzabile dalla tua implementazione personalizzata. Ti consigliamo che questo file sia leggibile in modo che tu e gli altri utenti della tua organizzazione possiate visualizzarlo nell'ispettore delle release.

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

      Il tuo 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.

Esempio di file dei risultati di rendering

Di seguito è riportato un output di esempio del file results.json di un rendering personalizzato:

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

Input per i deployment personalizzati

Per i deployment personalizzati, Cloud Deploy fornisce i seguenti input come variabili di ambiente:

  • CLOUD_DEPLOY_PROJECT

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

  • CLOUD_DEPLOY_PROJECT_ID

    L'ID progetto Google Cloud del progetto.

  • CLOUD_DEPLOY_LOCATION

    La Google Cloud regione 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 richiamata 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 l'implementazione.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Per l'implementazione personalizzata, questo valore è sempre DEPLOY.

  • CLOUD_DEPLOY_FEATURES

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

    Se la tua implementazione non supporta le funzionalità di questo elenco, ti consigliamo che non funzioni durante il rendering.

    Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornito da Cloud Deploy è CANARY, il deployment viene richiamato 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, viene chiamato il deployment personalizzato per ogni fase e questa variabile è impostata sulla percentuale canary per ogni fase. Il deployment deve essere eseguito 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 renderer personalizzato ha scritto i file di configurazione sottoposti a rendering.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Il percorso di Cloud Storage alla configurazione Skaffold sottoposta a rendering. Se hai fornito una configurazione di Skaffold con la release.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Il percorso Cloud Storage del file manifest sottoposto a rendering.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Il percorso della directory Cloud Storage in cui il container di deployment personalizzato deve caricare gli artefatti di deployment. Per ulteriori informazioni, consulta Output di custom deploy.

Output del deployment personalizzato

Il deployment personalizzato 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 operazione riuscita o non riuscita del deployment personalizzato.

    Di seguito sono riportati gli stati validi:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Questo vale per i deployment canary in cui le fasi canary vengono saltate per passare direttamente a stable.

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

    Il percorso è l'URI completo. Lo compili in parte utilizzando il valore di CLOUD_DEPLOY_OUTPUT_GCS_PATH fornito da Cloud Deploy.

    I file elencati qui vengono inseriti nelle risorse di esecuzione del job come artefatti di deployment.

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

    Questo messaggio viene utilizzato per compilare failure_message nell'esecuzione del job per questo deployment.

  • (Facoltativo) un messaggio di ignoramento, per fornire informazioni aggiuntive se la distribuzione restituisce lo stato SKIPPED.

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

    Il tuo target personalizzato crea questi metadati. Questi metadati vengono archiviati nell'esecuzione del job e nel rollout, 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 dei risultati del deployment di esempio

Di seguito è riportato un output di esempio del file results.json di un deployment personalizzato:

{
  "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 sui target personalizzati

Ecco alcuni aspetti da tenere presenti quando configuri e utilizzi i tipi di targeting personalizzati.

Esecuzione delle attività

Le attività di rendering e deployment personalizzate vengono eseguite nell'ambiente di esecuzione di Cloud Deploy. Non puoi configurare le attività da eseguire su un cluster Google Kubernetes Engine.

Target personalizzati e strategie di deployment

I target personalizzati sono completamente supportati per i deployment standard.

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

Devi utilizzare la configurazione canary personalizzata. I canary automatici e personalizzati non sono supportati con i target personalizzati.

Target personalizzati e parametri di deployment

Puoi utilizzare i parametri di implementazione con i target personalizzati. Puoi impostarli nella fase della pipeline di pubblicazione, 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 quelli già forniti.

Esempi di target personalizzati

Il repository cloud-deploy-samples contiene un insieme di implementazioni di destinazione personalizzate di esempio. Sono disponibili i seguenti campioni:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Ogni esempio include una guida rapida.

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

Passaggi successivi