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 tua pipeline di distribuzione:

1. Crea una o più applicazioni containerizzate che includano la funzionalità di deployment sul tuo target personalizzato e che soddisfino i requisiti di Cloud Deploy per i tipi di target personalizzati.

2. In skaffold.yaml, definisci un'azione personalizzata che faccia riferimento al container e specifichi il comando o i comandi da eseguire sul container.

3. Crea una definizione di CustomTargetType facendo riferimento all'azione personalizzata del passaggio precedente e registrala come risorsa Cloud Deploy.

4. Definisci un nuovo target con una proprietà customTarget che identifica il nuovo tipo di target personalizzato.

5. Fai riferimento al target dalla tua avanzamento della pipeline di distribuzione.

6. Crea una release.

Ciascuno di questi passaggi è descritto in dettaglio nel resto del presente documento.

Crea le tue applicazioni containerizzate

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

Sei tu a decidere il comportamento delle tue applicazioni. 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 target personalizzato creato. L'azione di rendering è facoltativa, ma se non ne fornisci una, Cloud Deploy utilizza il valore predefinito skaffold render.

Definisci le azioni personalizzate in Skaffold

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

Configuri ogni azione personalizzata per un target personalizzato in uno stato customActions. Per qualsiasi tipo di target personalizzato, puoi creare un'azione personalizzata, in Skaffold, per il rendering e una per il deployment. La definizione CustomTargetType identifica quale azione personalizzata viene utilizzata per il rendering e quale per il deployment.

Nota: il renderer personalizzato non è necessario se il tuo target personalizzato può utilizzare il file manifest generato dal renderer predefinito (skaffold render). In quasi tutti i casi, sarà necessaria un'azione di rendering personalizzata.

Di seguito è riportata la configurazione per le azioni di rendering e deployment personalizzati 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 Skaffold:

• customActions.name

  È un nome arbitrario per l'azione di rendering o deployment personalizzato. La definizione di CustomTargetType fa riferimento a questo nome, nella proprietà renderAction o deployAction.

• La stanza containers include il riferimento e i comandi per eseguire il container.

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

• customActions.containers.name

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

• image

  È il percorso dell'immagine container.

• command

  Il comando o i comandi da eseguire sul container.

• args

  È una raccolta di argomenti per command.

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

Nota: puoi anche definire le configurazioni Skaffold e archiviarle in un repository Git o in un bucket Cloud Storage e fare riferimento a queste configurazioni dalla tua definizione del tipo di destinazione personalizzata.

Definisci il tipo di target personalizzato

Per definire un target personalizzato, devi prima creare un tipo di target personalizzato utilizzando la configurazione CustomTargetType. Puoi creare CustomTargetType nello stesso file della definizione della pipeline di distribuzione, con le definizioni della 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 che assegni 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

  Indica 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 customAction.name definito in skaffold.yaml per l'azione deploy.

• includeSkaffoldModules

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

Usa configurazioni Skaffold remote

Puoi archiviare le configurazioni Skaffold in un repository Git pubblico, in un bucket Cloud Storage o in un repository Cloud Build di 2ª generazione e fare riferimento a queste configurazioni dalla definizione del tipo di destinazione personalizzata.

L'utilizzo di configurazioni Skaffold remote significa che per l'elemento skaffold.yaml fornito al momento del rilascio non è necessario definire le azioni personalizzate. In questo modo puoi condividere azioni personalizzate all'interno dell'organizzazione.

Per utilizzare le configurazioni Skaffold remote:

1. Crea una configurazione Skaffold con azioni personalizzate.

2. Archiviare la configurazione in un repository Git o in un bucket Cloud Storage.

3. Nella definizione del tipo di target personalizzato, aggiungi una stanza customActions.includeSkaffoldModules.

4. 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 da includere in ogni configurazione Skaffold. Se omesso, Cloud Deploy prende tutte le configurazioni nel percorso specificato.

   • Può essere una stanza googleCloudStorage, git o googleCloudBuildRepo.

     Per Cloud Storage:

     googleCloudStorage:
       source: PATH_TO_GCS_BUCKET
       path: FILENAME
     

     Per Git:

     git:
       repo: REPO_URL
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Per Cloud Build Repositories (2ª generazione):

      googleCloudBuildRepo:
       repository: PATH_TO_GCB_REPO
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Dove:

     PATH_TO_GCS_BUCKET è il percorso di una directory Cloud Storage, che termina con /*, dove sono archiviate le configurazioni Skaffold. Skaffold scarica tutti i file in questa directory, quindi trova il file Skaffold pertinente con le configurazioni, in base al percorso relativo configurato.

     PATH_TO_GCB_REPO è il percorso del repository Cloud Build di 2ª generazione in cui sono archiviate le configurazioni Skaffold. Il percorso ha il seguente formato: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. Skaffold scarica tutti i file in questa directory e poi trova il file Skaffold in base al percorso relativo configurato.

     FILENAME è il nome del file che include le configurazioni Skaffold. Questa proprietà path: è facoltativa. Se non la specifichi, Cloud Deploy presuppone il valore skaffold.yaml. Se non è presente skaffold.yaml o se il nome 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 Skaffold.

Esempio

Il seguente YAML personalizzato di tipo target è una stanza customActions con una stanza includeSkaffoldModules, che punta alle configurazioni 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

Registrare 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 vi fa riferimento. Non è necessario specificare il progetto se lo hai impostato come progetto 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 vi fa riferimento. Non è necessario specificare la regione se l'hai impostata come regione predefinita per gcloud CLI.

Ora che CustomTargetType viene creata come risorsa di Cloud Deploy, puoi utilizzarla in una definizione di Target per creare il tuo target personalizzato.

Per ulteriori informazioni sulla definizione di CustomTargetType, consulta la documentazione di riferimento allo schema di configurazione di Cloud Deploy.

Definisci il target

L'unica differenza tra una definizione di destinazione per un tipo di destinazione supportato e una definizione di destinazione personalizzata è che la definizione di destinazione personalizzata include una stanza customTarget. La sintassi di un 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.

Nota: puoi utilizzare più target quando i target secondari sono target personalizzati. In questo caso, tutti i target figlio devono essere dello stesso CustomTargetType.

Aggiungi il target alla pipeline di distribuzione

Puoi utilizzare un target personalizzato in una pipeline di distribuzione esattamente come useresti un tipo di target supportato. Ciò significa che non c'è differenza nella avanzamento della pipeline di distribuzione tra i target di un tipo di target supportato e quelli personalizzati.

Tutti i target in una pipeline di distribuzione devono usare lo stesso tipo di target. Ad esempio, non puoi avere una pipeline di distribuzione con alcuni target distribuiti in Google Kubernetes Engine e alcuni target personalizzati.

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

Crea una release

Nota: se non utilizzi configurazioni Skaffold remote, il file skaffold.yaml fornito per la release deve definire le azioni personalizzate richieste dal tipo di destinazione personalizzato.

Con il tipo di target personalizzato completamente definito e una destinazione creata per utilizzare quel tipo, 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, inclusa l'elaborazione dei parametri di deployment configurati nella release, nei target o nella pipeline di distribuzione. Cloud Deploy fornisce i parametri di deployment come input per il 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 visualizzati.

Per visualizzare l'output dell'azione di rendering personalizzato:

1. 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

2. Fai clic sul nome della pipeline di distribuzione.

   La visualizzazione della pipeline mostra lo stato del deployment dell'app e la tua release è elencata nella scheda Release in Dettagli pipeline di distribuzione.

3. Fai clic sul nome della release.

   Viene visualizzata la pagina Dettagli sulla release.

4. Fai clic sulla scheda Artefatti.

5. In Artefatti di destinazione, fai clic sulla freccia accanto a Visualizza artefatti.

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

   Puoi anche fare clic sul link Visualizza artefatti per visualizzare questi file per release, target o fase utilizzando la funzione di controllo della release.

Passaggi successivi

• Prova la guida rapida: definire e utilizzare un tipo di target personalizzato

• Consulta gli esempi di tipi di target personalizzati disponibili.

• Crea una pipeline di distribuzione e i target.

• Scopri di più sulla configurazione dei target di Cloud Deploy