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 Cloud Deploy.

Di seguito è riportata la procedura di alto livello per creare un tipo di target personalizzato e usarlo nella pipeline di distribuzione:

  1. Crea un'applicazione containerizzata o più applicazioni che includono la funzionalità di deployment nel target personalizzato e che soddisfano i requisiti di Cloud Deploy per i tipi di target personalizzati.

  2. Definisci un'azione personalizzata in skaffold.yaml che fa riferimento al contenitore e specifica il comando o i comandi da eseguire al suo interno.

  3. Crea una definizione CustomTargetType che fa 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 a questo target dalla progressione della pipeline di pubblicazione.

  6. Crea una release.

Ciascuno di questi passaggi è descritto nel resto del documento.

Crea le tue applicazioni containerizzate

La funzionalità di deployment nel target personalizzato è definita nelle applicazioni containerizzate, che fornisci a Cloud Deploy facendovi riferimento dal file skaffold.yaml. Quando la pipeline di distribuzione include un target che utilizza un tipo di target personalizzato, Cloud Deploy chiama i contenitori 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 tue 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 contenitore 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 quella predefinita skaffold render.

Definire le azioni personalizzate in Skaffold

Una volta create le immagini container per le azioni personalizzate, fai riferimento a queste nel file di configurazione di skaffold.yaml.

Ogni azione personalizzata per un target personalizzato viene configurata in una customActions stanza. Per qualsiasi tipo di target personalizzato, in Skaffold devi creare un'azione personalizzata per il rendering e un'altra per il deployment. La definizione CustomTargetType identifica l'azione personalizzata utilizzata per il rendering e quella utilizzata per il deployment.

Di seguito è riportata la configurazione per le azioni di rendering e deployment personalizzate 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 di 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, oltre ai comandi per eseguire il container.

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

  • customActions.containers.name

    È un nome arbitrario per il contenitore specifico che utilizzi per questa azione. Come best practice, questo nome del contenitore deve sempre essere qualificato SHA.

  • image

    È il percorso dell'immagine del contenitore.

  • command

    È il comando o i comandi da eseguire nel contenitore.

  • args

    È una raccolta di argomenti per command.

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

Definisci il tipo di target personalizzato

Per definire un target personalizzato, devi prima creare un tipo di target personalizzato utilizzando la CustomTargetTypeconfigurazione. Puoi creare CustomTargetType nello stesso file della definizione della pipeline di importazione, con le definizioni dei target 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. A questo nome viene fatto 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 personalizzata. Questo valore è il customAction.name definito in skaffold.yaml per l'azione render.

  • DEPLOY_ACTION_NAME

    È il nome dell'azione di deployment personalizzata. 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 Utilizzare le configurazioni Skaffold remote.

Utilizzare le configurazioni di Skaffold remote

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

L'utilizzo delle configurazioni Skaffold remote significa che il skaffold.yaml fornito al momento del rilascio non deve avere le azioni personalizzate definite. In questo modo, puoi condividere le azioni personalizzate all'interno dell'organizzazione.

Per utilizzare le configurazioni di Skaffold remote:

  1. Crea una configurazione Skaffold con le azioni o l'azione personalizzata.

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

    • 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 i repository Cloud Build (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 /*, in cui sono memorizzate le configurazioni di Skaffold. Skaffold scarica tutti i file di questa directory e poi trova il file Skaffold pertinente con le configurazioni in base al percorso relativo configurato.

      PATH_TO_GCB_REPO è il percorso del repository Cloud Build 2ª generazione. in cui sono memorizzate le configurazioni di Skaffold. Il percorso ha la seguente forma: 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 di Skaffold. Questa proprietà path: è facoltativa. Se non la specifichi, Cloud Deploy assume skaffold.yaml. Se non è presente skaffold.yaml o se il nome file specificato non è presente, la creazione della release non va a buon fine.

      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 file YAML di tipo target personalizzato è una stanza customActions con una stanza includeSkaffoldModules che rimanda 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 codice 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 a CustomTargetType. 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 fa riferimento. Non è necessario specificare la regione se la hai impostata come regione predefinita per la gcloud CLI.

Ora che CustomTargetType è stato creato come risorsa Cloud Deploy, puoi utilizzarlo in una definizione Target per creare il tuo target personalizzato.

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

Definisci il tuo target

L'unica differenza tra una definizione di target per un tipo di target supportato e una definizione di target personalizzato è che quest'ultima 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 definita nella configurazione del tipo di destinazione personalizzato.

Aggiungi il target alla pipeline di pubblicazione

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

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

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

Crea una release

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

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 personalizzata viene eseguita per ogni destinazione nella pipeline di distribuzione, inclusa l'elaborazione dei parametri di deployment configurati sulla release, sui target o sulla pipeline di distribuzione. Cloud Deploy fornisce i parametri di deployment come input al contenitore di rendering personalizzato.

Visualizzare l'output dei target personalizzati

Se l'azione personalizzata soddisfa i requisiti per i target personalizzati, puoi utilizzare Google Cloud Console per visualizzare gli elementi visualizzati.

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

  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 pubblicazione

  2. Fai clic sul nome della pipeline di importazione.

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

  3. Fai clic sul nome della release.

    Viene visualizzata la pagina Dettagli sulla release.

  4. Fai clic sulla scheda Elementi.

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

    Vengono elencati gli elementi visualizzati, tra cui il file skaffold.yaml e il file manifest visualizzati generati dal visualizzatore personalizzato. Puoi anche fare clic sul link Posizione di archiviazione accanto a ciascun file per accedere al bucket Cloud Storage e visualizzarli.

    Puoi anche fare clic sul link Visualizza elementi per visualizzare i file per release, target o fase utilizzando lo strumento di controllo release.

Passaggi successivi