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 generale per creare un tipo di target personalizzato e nella tua 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 tua pipeline di distribuzione include un target che utilizza un tipo di target personalizzato, Cloud Deploy chiama i container con azioni personalizzate definiti per questo un 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 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 La definizione di CustomTargetType fa riferimento a questo nome, in renderAction o la proprietà deployAction.

  • La stanza containers include il tuo riferimento, oltre ai comandi per eseguire il container.

    La stanza containers consente più di un container, ma Google consiglia ne utilizzi 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 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 tua pipeline di distribuzione definizione di target, con le definizioni del 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

    Indica il nome dell'azione di rendering personalizzato. Questo valore è il customAction.name definita in skaffold.yaml per render.

  • DEPLOY_ACTION_NAME

    È il nome dell'azione di deployment personalizzata. Questo valore è il customAction.name definita in skaffold.yaml per deployment.

  • 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 Skaffold in un repository Git pubblico, nel bucket Cloud Storage o nel repository Cloud Build 2ª generazione) fare riferimento a queste configurazioni dalla definizione del tipo di target personalizzato.

L'utilizzo di configurazioni Skaffold remote significa che il skaffold.yaml che fornisci non è necessario definire azioni personalizzate per ora del rilascio. Ciò consente condividendo azioni personalizzate all'interno dell'organizzazione.

Per utilizzare le configurazioni di Skaffold remote:

  1. Crea una configurazione Skaffold con azioni personalizzate.

  2. Archiviare la configurazione in un repository Git o in un nel 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 a metadata.name in ogni configurazione Skaffold da includere. Se questo viene omesso, Cloud Deploy accetta 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 i repository Cloud Build (2ª gen.):

       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 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ª gen. in cui sono memorizzate le configurazioni di Skaffold. Il percorso assume 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 di Skaffold. Questa proprietà path: è facoltativa. Se non la specifichi, Cloud Deploy assume skaffold.yaml. Se non vengono skaffold.yaml o se il nome file specificato non è presente, l'elemento la creazione della release non riesce.

      REPO_URL è l'URL del repository Git.

      PATH_TO_FILE è il percorso nel repository del file contenente Configurazioni Skaffold.

      BRANCH_NAME è il nome del ramo (ad esempio main) da cui prendiamo le configurazioni di Skaffold.

Esempio

Il seguente YAML di tipo target personalizzato è una stanza customActions con un includeSkaffoldModules stanza, che punta alle configurazioni Skaffold archiviate in 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 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 il tuo 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 disponi impostala come regione predefinita per gcloud CLI.

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

Per ulteriori informazioni sulla definizione di CustomTargetType, consulta le Riferimento allo schema di configurazione di Cloud Deploy.

Definisci il target

L'unica differenza tra una definizione di destinazione per un tipo di target supportato e Una definizione di target personalizzato prevede che la definizione di un target personalizzato includa un customTarget stanza. 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 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. Cioè, non c'è alcuna differenza nella pipeline di distribuzione avanzamento tra i target di un tipo di target supportato e quelli 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 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 parametri di deployment come input al container di rendering personalizzato.

Visualizzare l'output dei target personalizzati

Se la tua azione personalizzata soddisfa le requisiti per le destinazioni personalizzate, puoi utilizzare la console Google Cloud per visualizzare artefatti.

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

  1. Nella console Google Cloud, vai a Cloud Deploy Pagina Pipeline di distribuzione 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 è elencata nella scheda Release nella sezione Pipeline di distribuzione dettagli.

  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 sottoposti a rendering, tra cui l'oggetto skaffold.yaml sottoposto a rendering e il file manifest sottoposto a rendering generato dal renderer personalizzato. Puoi inoltre fai clic sul link Posizione archiviazione accanto a ciascuno di essi per passare bucket Cloud Storage per visualizzare i file.

    Puoi anche fare clic sul link Visualizza elementi per visualizzare questi file per alla release, per target o per fase, utilizzando release inspector.

Passaggi successivi