Creare un target personalizzato

Questo documento descrive come creare un tipo di target Cloud Deploy personalizzato e utilizzarlo come target in una pipeline di distribuzione di Cloud Deploy.

Di seguito è riportato il processo generale per creare un tipo di target personalizzato e utilizzarlo nella pipeline di distribuzione:

Crea una o più applicazioni containerizzate che includano la funzionalità di cui eseguire il deployment nel tuo target personalizzato e che soddisfino i requisiti di Cloud Deploy per i tipi di target personalizzati.
Definisci un'azione personalizzata in skaffold.yaml che faccia riferimento al container e specifichi il comando o i comandi da eseguire al suo interno.
Crea una definizione CustomTargetType che faccia riferimento all'azione personalizzata del passaggio precedente e registrala come risorsa Cloud Deploy.
Definisci un nuovo target con una proprietà customTarget che identifica il nuovo tipo di target personalizzato.
Fai riferimento a quel target dall'avanzamento della pipeline di distribuzione.
Crea una release.

Ciascuno di questi passaggi è descritto dettagliatamente nel resto del documento.

Crea le tue applicazioni containerizzate

La funzionalità per il deployment nel target personalizzato è definita nelle applicazioni containerizzate, che fornisci a Cloud Deploy tramite riferimento a queste applicazioni nel tuo file skaffold.yaml. Quando la tua pipeline di distribuzione include una destinazione che utilizza un tipo di target personalizzato, Cloud Deploy chiama i container di azioni personalizzate definiti per quel tipo di target personalizzato, in Skaffold, per eseguire le azioni di rendering e deployment che hai definito.

Il comportamento delle applicazioni dipende da te. Tuttavia, deve utilizzare le variabili di ambiente di input fornite da Cloud Deploy e deve restituire gli output richiesti.

Nella maggior parte dei casi, creerai un container per l'azione di rendering e uno per l'azione di deployment, per ogni tipo di destinazione personalizzato creato. L'azione di rendering è facoltativa, ma se non ne specifichi una, Cloud Deploy utilizza il valore predefinito skaffold render.

Definisci le azioni personalizzate in Skaffold

Dopo aver impostato le immagini o le immagini container delle azioni personalizzate, puoi farvi riferimento nel file di configurazione di skaffold.yaml.

Puoi configurare ogni azione personalizzata per un target personalizzato in una stanza customActions. Per ogni tipo di target personalizzato, crei un'azione personalizzata, in Skaffold, per il rendering e una per il deployment. La definizione di CustomTargetType identifica quale azione personalizzata viene utilizzata per il rendering e quale viene utilizzata per il deployment.

Di seguito è riportata la configurazione per le azioni di rendering e deployment personalizzato in skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

In questa configurazione di Skaffold:

customActions.name

Nome arbitrario per l'azione di rendering o deployment personalizzato. La definizione di CustomTargetType fa riferimento a questo nome, nella proprietà renderAction o nella proprietà deployAction.
La stanza containers include il tuo riferimento e i comandi per eseguirlo.

La stanza containers consente più di un container, ma Google consiglia di usarne solo uno.
customActions.containers.name

È un nome arbitrario per il contenitore specifico che stai utilizzando per questa azione. Come best practice, questo nome container deve essere sempre qualificato SHA.
image

È il percorso dell'immagine container.
command

Comando o comandi da eseguire sul container.
args

È una raccolta di argomenti per command.

Consulta il riferimento YAML di Skaffold per la documentazione dettagliata sulle proprietà di configurazione utilizzate in customActions.

Definisci il tipo di target personalizzato

Per definire un target personalizzato, crea prima un tipo di target personalizzato utilizzando la configurazione di CustomTargetType. Puoi creare CustomTargetType nello stesso file della definizione della pipeline di distribuzione, con le definizioni di destinazione o in un file separato.

La definizione di CustomTargetType è la seguente:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

Dove

CUSTOM_TARGET_TYPE_NAME

È un nome arbitrario assegnato a questa definizione del tipo di target personalizzato. Questo nome fa riferimento nella definizione del target per qualsiasi target che utilizza il tipo di target personalizzato che stai definendo.
RENDER_ACTION_NAME

È il nome dell'azione di rendering personalizzato. Questo valore è il valore customAction.name definito in skaffold.yaml per l'azione render.
DEPLOY_ACTION_NAME

È il nome dell'azione di deployment personalizzato. Questo valore è il valore customAction.name definito in skaffold.yaml per l'azione deploy.
includeSkaffoldModules

È una stanza facoltativa da utilizzare se utilizzi configurazioni di Skaffold remote. Le proprietà in questa stanza sono mostrate nella sezione Utilizzare configurazioni Skaffold remote.

Utilizzare configurazioni Skaffold remote

Puoi archiviare le configurazioni Skaffold in un repository Git pubblico o in un bucket Cloud Storage e fare riferimento a queste configurazioni dalla definizione del tipo di destinazione personalizzato.

Utilizzando le configurazioni Skaffold remote, non è necessario definire azioni personalizzate per skaffold.yaml che fornisci al momento del rilascio. Ciò consente di condividere azioni personalizzate all'interno dell'organizzazione.

Per utilizzare le configurazioni Skaffold remote:

Crea una configurazione Skaffold con azioni o azioni personalizzate.
Archivia la configurazione in un repository Git o in un bucket Cloud Storage.
Nella definizione del tipo di target personalizzato, aggiungi una stanza customActions.includeSkaffoldModules.
In includeSkaffoldModules, specifica quanto segue:
- (Facoltativo) Uno o più elementi configs:
  
  - configs: ["name1", "name2"]
  
  Il valore di configs è un elenco di stringhe che corrispondono alla proprietà metadata.name in ogni configurazione Skaffold da includere. Se omesso, Cloud Deploy utilizza tutte le configurazioni nel percorso specificato.
- Una stanza in googleCloudStorage o in una stanza git.
  
  Per Cloud Storage:
```
googleCloudStorage:
  source: PATH_TO_GCS_BUCKET
  path: FILENAME
```
  Per Git:
```
git:
  repo: REPO_URL
  path: PATH_TO_FILE
  ref: BRANCH_NAME
```
  Dove:
  
  PATH_TO_GCS_BUCKET è il percorso di una directory Cloud Storage, che termina con /*, in cui sono archiviate le configurazioni di Skaffold. Skaffold scarica tutti i file in questa directory, quindi trova il file Skaffold pertinente con le configurazioni, in base al percorso relativo configurato.
  
  FILENAME è il nome del file che include le configurazioni di Skaffold. Questa proprietà path: è facoltativa; se non la specifichi, Cloud Deploy presuppone skaffold.yaml. Se skaffold.yaml non è presente o se il nome del file specificato non è presente, la creazione della release non riesce.
  
  REPO_URL è l'URL del repository Git.
  
  PATH_TO_FILE è il percorso nel repository del file contenente le configurazioni Skaffold.
  
  BRANCH_NAME è il nome del ramo (ad esempio, main) da cui recuperare le configurazioni di Skaffold.

Esempio

Il seguente codice YAML di tipo target personalizzato è una stanza customActions con una stanza includeSkaffoldModules, che punta alle configurazioni di Skaffold archiviate in un bucket Cloud Storage:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

Il seguente YAML è una configurazione Skaffold a cui fa riferimento l'azione personalizzata mostrata:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Registra il tipo di target personalizzato

Dopo aver configurato CustomTargetType, esegui il comando gcloud deploy apply per registrare la risorsa CustomTargetType in un progetto Google Cloud:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Dove:

FILE è il nome del file in cui hai definito questo tipo di target personalizzato.

PROJECT è il progetto Google Cloud in cui creare questa risorsa. CustomTargetType deve trovarsi nello stesso progetto della risorsa Target che fa riferimento. Non è necessario specificare il progetto se lo hai impostato come predefinito per Google Cloud CLI.

REGION è la regione (ad esempio us-centra1) in cui creare questa risorsa. CustomTargetType deve trovarsi nella stessa regione della risorsa Target che lo fa riferimento. Non è necessario specificare la regione se l'hai impostata come regione predefinita per gcloud CLI.

Con CustomTargetType ora creato come risorsa di Cloud Deploy, puoi utilizzarlo in una definizione di Target per creare il tuo target personalizzato.

Per maggiori informazioni sulla definizione di CustomTargetType, consulta il riferimento sullo schema di configurazione di Cloud Deploy.

Definisci il target

L'unica differenza tra una definizione di target per un tipo di target supportato e una definizione di target personalizzata è che la definizione di target personalizzato include una stanza customTarget. La sintassi di customTarget è la seguente:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Dove CUSTOM_TARGET_TYPE_NAME è il valore della proprietà name definito nella configurazione del tipo di target personalizzato.

Aggiungi il target alla pipeline di distribuzione

Puoi utilizzare un target personalizzato in una pipeline di distribuzione esattamente come faresti con un tipo di target supportato. In altre parole, non c'è alcuna differenza nell'avanzamento della pipeline di distribuzione tra i target di un tipo di target supportato e i target personalizzati.

Tutti i target in una pipeline di distribuzione devono utilizzare lo stesso tipo di target. Ad esempio, non puoi avere una pipeline di distribuzione con alcune destinazioni di deployment in Google Kubernetes Engine e alcune destinazioni personalizzate.

Come per i tipi di target supportati, puoi includere i parametri di deployment nella fase della pipeline.

Crea una release

Una volta che il tipo di target personalizzato è completamente definito e un target creato per utilizzarlo, ora puoi creare una release nel modo normale:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Al momento della creazione della release, l'azione di rendering personalizzato viene eseguita per ogni target nella pipeline di distribuzione, compresa l'elaborazione dei parametri di deployment configurati nella release, nelle destinazioni o nella pipeline di distribuzione. Cloud Deploy fornisce i parametri di deployment come input al container di rendering personalizzato.

Visualizzare l'output dei target personalizzati

Se l'azione personalizzata soddisfa i requisiti per i target personalizzati, puoi utilizzare la console Google Cloud per visualizzare gli artefatti sottoposti a rendering.

Segui questi passaggi per visualizzare l'output della tua azione di rendering personalizzato.

Nella console Google Cloud, vai alla pagina pipeline di distribuzione di Cloud Deploy per visualizzare la pipeline di distribuzione.

Apri la pagina Pipeline di distribuzione
Fai clic sul nome della pipeline di distribuzione.

La visualizzazione della pipeline mostra lo stato del deployment dell'app e la release è elencata nella scheda Release della sezione Dettagli pipeline di pubblicazione.
Fai clic sul nome della release.

Viene visualizzata la pagina Dettagli sulla release.
Fai clic sulla scheda Artefatti.
In Elementi di destinazione, fai clic sulla freccia accanto a Visualizza elementi.

Vengono elencati gli artefatti sottoposti a rendering, inclusi skaffold.yaml e il file manifest visualizzato, generato dal renderer personalizzato. Puoi anche fare clic sul link Posizione di archiviazione accanto a ogni file per accedere al bucket Cloud Storage e visualizzare i file.

Puoi anche fare clic sul link Visualizza elementi per visualizzare questi file in base alla release, al target o alla fase utilizzando lo strumento Controllo delle release.

Passaggi successivi

Prova la guida rapida: definire e utilizzare un tipo di target personalizzato
Guarda gli esempi di tipi di target personalizzati disponibili.
Crea i target e una pipeline di distribuzione.
Scopri di più sulla configurazione delle destinazioni di Cloud Deploy