Informazioni sui target personalizzati

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

Cloud Deploy include supporto integrato per vari runtime ambienti come target. Ma l'elenco i tipi di destinazione supportati sono limitati. Con i target personalizzati, puoi eseguire il deployment a sistemi diversi oltre ai runtime supportati.

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

Nella pagina Crea un target personalizzato viene descritta la il processo per definire un tipo di target personalizzato e implementarlo come target nella una pipeline di distribuzione.

Come funziona un target personalizzato?

Ogni target personalizzato è costituito dai seguenti componenti:

  • Azioni personalizzate, definita in skaffold.yaml

    Sono simili a come definisci gli hook di deployment. Nella skaffold.yaml, tu definisci customActions, in cui ogni azione personalizzata identifica l'immagine container da utilizzare e i comandi da eseguire su quel container.

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

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

    L'azione di rendering personalizzato è facoltativa, ma devi crearne una a meno che il target personalizzato funzionerà correttamente se visualizzato da skaffold render, ovvero l'impostazione predefinita per Cloud Deploy.

  • Una definizione del tipo di target personalizzato

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

  • Una definizione del target

    La definizione di 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 qualsiasi altro target, facendovi riferimento all'avanzamento della pipeline di distribuzione e sfruttando appieno le funzionalità di Cloud Deploy, come promozioni e approvazioni, e rollback.

Esempio

Guida rapida Definire e utilizzare un tipo di target personalizzato crea un tipo di target personalizzato che include comandi semplici da eseguire su una container, un comando per il rendering e uno per il deployment. I comandi, in questo caso, è sufficiente aggiungere del testo ai file di output richiesti per il rendering 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 di input e output, sia per il rendering che per il deployment. Questa sezione elenca quali input e output sono obbligatori e il modo in cui vengono forniti.

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

I parametri di deployment intesi come input per i target personalizzati devono iniziare con customTarget/, ad esempio customTarget/vertexAIModel. Quando si fa riferimento a un utilizza la seguente sintassi:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Dove VAR_NAME è il nome che segue la barra nella il nome del parametro di deployment. Ad esempio, se definisci una parametro di deployment denominato customTarget/vertexAIModel, come riferimento CLOUD_DEPLOY_customTarget_vertexAIModel.

Input per il rendering delle azioni

Per azioni di rendering personalizzate, Cloud Deploy fornisce quanto segue come input obbligatori, come variabili di ambiente. Per implementazioni multifase (deployment canary), Cloud Deploy fornisce queste variabili per ogni fase.

  • CLOUD_DEPLOY_PROJECT

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

  • CLOUD_DEPLOY_LOCATION

    La regione Google Cloud per il tipo di target personalizzato.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

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

  • CLOUD_DEPLOY_RELEASE

    Il nome della release per cui viene richiamata l'operazione di rendering.

  • CLOUD_DEPLOY_TARGET

    Il nome della destinazione Cloud Deploy che utilizza la destinazione personalizzata di testo.

  • CLOUD_DEPLOY_PHASE

    La fase di implementazione a cui corrisponde il rendering.

  • CLOUD_DEPLOY_REQUEST_TYPE

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

  • CLOUD_DEPLOY_FEATURES

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

    Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo per evitare errori durante il rendering.

    Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornita da Cloud Deploy è CANARY, l'azione di rendering è per ogni fase nella versione canary. La percentuale canary per ogni fase è specificata 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, la tua variabile personalizzata di rendering viene richiesta per ogni fase e questa variabile è impostata su percentuale canary per ogni fase. Per distribuzioni standard e per i deployment canary che hanno raggiunto la fase stable, è 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    Il fornitore di spazio di archiviazione. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    Il percorso Cloud Storage per l'archivio del file di rendering scritto al momento della release è stata creata.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Percorso Cloud Storage in cui si trova il container di rendering personalizzato dovrebbe caricare gli artefatti da usare per il deployment. Tieni presente che il rendering deve caricare un file denominato results.json contenente i risultati di questa dell'operazione di rendering. Per ulteriori informazioni, vedi Output da un'azione di rendering.

Output dell'azione di rendering

L'azione di rendering personalizzata deve fornire le informazioni descritte in questo articolo . Le informazioni devono essere incluse nel file dei risultati, denominato results.json, situato nel bucket Cloud Storage fornito da con Cloud Deploy.

  • File o file di configurazione sottoposti a rendering

  • Un file results.json contenente le seguenti informazioni:

    • Un'indicazione dello stato di riuscita o non riuscita dell'azione personalizzata.

      I valori validi sono SUCCEEDED e FAILED.

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

    • Il percorso Cloud Storage del file di configurazione di cui è stato eseguito il rendering .

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

      Devi fornire il file di configurazione visualizzato, anche se è vuoto. La i contenuti del file possono essere qualsiasi cosa e in qualsiasi formato, purché fruibile dall'azione di deployment personalizzata. Consigliamo che questo file sia una persona leggibile in modo che tu e gli altri utenti della tua organizzazione possiate visualizzare nello strumento di controllo delle release.

    • (Facoltativo) Una mappa dei metadati da includere

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

Se devi esaminare il file results.json, ad esempio per il debug, individua il rispettivo URI Cloud Storage nei log di Cloud Build.

Esempio di file dei risultati di rendering

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

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

Input per il deployment delle azioni

Per azioni di deployment personalizzate, Cloud Deploy fornisce quanto segue input obbligatori, come variabili di ambiente:

  • CLOUD_DEPLOY_PROJECT

    Il progetto Google Cloud in cui viene creata la destinazione personalizzata.

  • CLOUD_DEPLOY_LOCATION

    La regione Google Cloud per il tipo di target personalizzato.

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

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

  • CLOUD_DEPLOY_RELEASE

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

  • CLOUD_DEPLOY_ROLLOUT

    Il nome dell'implementazione di Cloud Deploy a cui è destinato questo deployment.

  • CLOUD_DEPLOY_TARGET

    Il nome della destinazione Cloud Deploy che utilizza la destinazione personalizzata di testo.

  • 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 di funzionalità di Cloud Deploy che che il container deve supportare. Questa variabile viene compilata in base alle caratteristiche configurate nella pipeline di distribuzione.

    Se la tua implementazione non supporta le funzionalità in questo elenco, ti consigliamo per evitare errori durante il rendering.

    Per i deployment standard, questo campo è vuoto. Per i deployment canary, il valore è CANARY. Se il valore fornita da Cloud Deploy è CANARY, l'azione di rendering è per ogni fase nella versione canary. La percentuale canary per ogni fase è specificata 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, la tua variabile personalizzata di deployment viene richiamata per ogni fase e questa variabile è impostata sul percentuale 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 renderer personalizzato ha scritto il rendering di configurazione dei deployment.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    Percorso Cloud Storage della configurazione Skaffold sottoposta a rendering.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    Percorso Cloud Storage del file manifest sottoposto a rendering.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    Il percorso della directory Cloud Storage in cui viene eseguito il deployment personalizzato del container dovrebbe caricare gli artefatti di deployment. Per ulteriori informazioni, vedi Output dell'azione di deployment.

Output dall'azione di deployment

L'azione di deployment personalizzata deve scrivere un file di output results.json. Questo file devono 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 dell'azione di deployment personalizzato.

    Di seguito sono riportati gli stati validi:

  • (Facoltativo) Un elenco dei file degli artefatti di deployment, sotto forma di Percorsi Cloud Storage

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

    I file elencati qui sono compilati in risorse job di esecuzione come artefatti di deployment.

  • (Facoltativo) Un messaggio di errore se l'azione di deployment personalizzato non va a buon fine (viene restituito uno stato FAILED)

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

  • (Facoltativo) Un messaggio di salto, per fornire ulteriori informazioni se l'azione restituisce un SKIPPED.

  • (Facoltativo) Una mappa dei metadati da includere

    Il target personalizzato crea questi metadati. Questi metadati vengono archiviati esecuzione del job e sull'implementazione, nel campo custom_metadata.

Se devi esaminare il file results.json, ad esempio per il debug, individua il relativo URI Cloud Storage in Cloud Build log di rendering della release.

Esempio di file dei risultati del deployment

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

{
  "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 presente durante la configurazione e l'utilizzo del target personalizzato di testo.

Esecuzione delle azioni personalizzate

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

Utilizzo di configurazioni Skaffold remote e riutilizzabili

Come descritto in questo documento, configuri l'azione personalizzata nel skaffold.yaml file fornito al momento della creazione della release. Ma puoi anche archiviare configura Skaffold in un repository Git o in un bucket Cloud Storage come riferimento dalla definizione del tipo di target personalizzato. Questo ti consente di utilizzare azioni personalizzate definite e archiviate in un'unica invece di includere le azioni personalizzate negli elementi pubblicitari di ogni release. skaffold.yaml.

Target personalizzati e strategie di deployment

I target personalizzati sono pienamente supportati i deployment standard.

Cloud Deploy supporta deployment canary a condizione che il renderer personalizzato e il deployer supportano la funzionalità canary.

Devi utilizzare la configurazione canary personalizzata. Automatici e personalizzati le versioni canary non sono supportate.

Target personalizzati e parametri di deployment

Puoi utilizzare i parametri di deployment con target personalizzati. Puoi impostarle nella pipeline di distribuzione stage, sul target che utilizza un tipo di target personalizzato o release.

I parametri di deployment vengono passati ai container di rendering e di deployment personalizzati, variabili di ambiente, oltre alle quelli già forniti.

Esempi di target personalizzati

Il repository cloud-deploy-samples contiene un insieme di implementazioni di target personalizzate di esempio. I seguenti esempi sono disponibili:

  • 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 è coperto da un contratto di assistenza Google Cloud. Per segnalare bug o inviare una richiesta in un prodotto Google Cloud, contatta Google Cloud assistenza in tempo reale.

Passaggi successivi