Trasferire i parametri al deployment

Con Cloud Deploy, puoi trasmettere i parametri per la release e questi valori vengono forniti al file manifest o ai file manifest prima che i file manifest vengano applicati ai rispettivi target. Questa sostituzione viene eseguita dopo il rendering dei manifest, come passaggio finale dell'operazione di rendering di Cloud Deploy. Vengono forniti valori per tutti i manifest identificati nel file skaffold.yaml che contengono i segnaposto corrispondenti.

Devi solo includere i segnaposto nel manifest e impostarne i valori nella pipeline di distribuzione o nella configurazione di destinazione di Cloud Deploy oppure al momento della creazione di una release.

Questo articolo spiega come farlo.

Perché utilizzare i parametri di deployment?

In genere, ciò prevede l'applicazione di valori diversi ai manifest per destinazioni diverse in un deployment parallelo. Tuttavia, puoi utilizzare i parametri di deployment per tutto ciò che richiede la sostituzione di una coppia chiave-valore post-rendering nel manifest.

Come funziona

I seguenti passaggi descrivono il processo generale per la configurazione dei parametri di deployment e l'indicazione dei valori:

  1. Puoi configurare la parametrizzazione del deployment, come descritto qui.

    È incluso quanto segue:

    • Aggiungi i segnaposto al file manifest.

    • Aggiungi i valori per i segnaposto.

      Puoi farlo in tre modi, descritti qui.

  2. Quando crei una release, viene visualizzato il manifest.

    Se inizi con un manifest basato su modelli, ora i valori vengono applicati alle variabili del modello. Se inizi con un manifest non elaborato, questo rimane invariato. Il rendering è eseguito da Skaffold.

    Tuttavia, puoi avere ulteriori variabili nel manifest per le quali i valori non vengono applicati al momento del rendering. Questi sono i parametri di deployment descritti in questo documento.

    Al momento della creazione della release, tutti i parametri di deployment vengono compilati in un dizionario, che viene utilizzato per sostituire i valori prima dell'applicazione dei manifest.

  3. Dopo il rendering, Cloud Deploy sostituisce i valori dei parametri di deployment.

    Questi sono i valori configurati nel primo passaggio.

    Il processo di rendering applicava già valori ai modelli di manifest, sostituendo alcuni valori e aggiungendo etichette specifiche per Cloud Deploy. Tuttavia, i valori di questi parametri di deployment vengono sostituiti dopo il rendering. Le differenze tra i modelli di manifest e i parametri di deployment sono descritte qui.

  4. Il manifest viene applicato al runtime di destinazione per eseguire il deployment dell'applicazione.

    Sono inclusi i valori sostituiti al momento del rendering e i valori per tutti i parametri del deployment

Diversi modi per trasferire i valori

Puoi fornire i parametri e i valori per questi parametri in tre modi:

  • Nella definizione della pipeline di distribuzione

    Devi fornire il parametro e il relativo valore nella definizione di una fase dell'avanzamento della pipeline di distribuzione. Il parametro viene passato al target rappresentato da quella fase. Se quella fase fa riferimento a un target multiplo, i valori impostati qui vengono utilizzati per tutti i target figlio.

    Questo metodo consente di sostituire un valore per tutte le release in una determinata pipeline, per tutti i target interessati. I parametri definiti per una fase identificano un'etichetta e il target corrispondente per quella fase deve avere un'etichetta corrispondente.

  • Nella definizione del target

    Puoi configurare il parametro e il relativo valore nella definizione per il target stesso. Questo metodo consente di sostituire un valore per quel target per tutte le release.

  • Nella riga di comando, quando crei una release

    Puoi includere il parametro e il relativo valore utilizzando il flag --deploy-parameters nel comando gcloud deploy releases create.

    Questo metodo consente di sostituire un valore al momento della creazione della release, applicando questo valore ai manifest di tutti i target interessati.

La configurazione è spiegata in modo più dettagliato qui.

Posso utilizzare più di uno di questi metodi?

Sì, puoi includere i parametri di deployment nella fase della pipeline, nella configurazione di destinazione e nella riga di comando. Il risultato è che tutti i parametri vengono accettati e aggiunti al dizionario. Tuttavia, se un parametro specifico viene passato in più posizioni, ma con valori diversi, il comando gcloud deploy releases create ha esito negativo e genera un errore.

Eseguire il deployment dei parametri con target personalizzati

Puoi utilizzare qualsiasi parametro di deployment come variabili di ambiente nelle destinazioni personalizzate. In questo caso, utilizza la syntax specificata per i target personalizzati.

Differenze rispetto ai modelli manifest

I parametri di deployment, come descritto in questo articolo, vengono distinti dai segnaposto in un manifest basato su modelli tramite la syntax. Tuttavia, se ti stai chiedendo perché potresti aver bisogno dei parametri di deployment invece di utilizzare solo le tecniche standard per i manifest basati su modelli, la seguente tabella mostra i diversi scopi:

Tecnica Ora di sostituzione Applicabile a
Modello manifest Fase di rendering Release specifica; target specifico
Sulla riga di comando Post-rendering Release specifica; tutti i target
Pipeline di distribuzione Post-rendering Tutte le release; target specifici (per etichetta)
In linea con l'obiettivo Post-rendering Tutte le release; target specifico

Questo documento riguarda solo i parametri di deployment (nella riga di comando, nella pipeline e nella destinazione), non nei manifest basati su modelli.

Limitazioni

  • Per ogni tipo di parametro, puoi creare un massimo di 25 parametri.

  • Un target figlio può ereditare inoltre fino a 25 parametri dal target multiplo principale, fino a un massimo di 100 parametri sulle destinazioni, inclusi quelli impostati nella fase della pipeline.

  • Il nome della chiave è limitato a un massimo di 63 caratteri e alla seguente espressione regolare:

    ^[a-zA-Z0-9]([-A-Za-z0-9_.]{0,61}[a-zA-Z0-9])?$

    Un'eccezione è rappresentata dal fatto che utilizzi un parametro di deployment come variabile di ambiente in un target personalizzato, devi inserire una barra tra la parola chiave customTarget e il nome della variabile (customTarget/VAR_NAME). Consulta la sezione Input e output obbligatori per conoscere la sintassi supportata.

  • Il prefisso CLOUD_DEPLOY_ è riservato e non può essere utilizzato per il nome di una chiave.

  • Non puoi avere due chiavi con lo stesso nome applicate alla stessa destinazione.

  • Il valore può essere vuoto, ma può contenere al massimo 512 caratteri.

  • I segnaposto dei parametri di deployment non possono essere utilizzati per i valori di configurazione Helm, ma devono essere trasmessi per convenzione.

Configura i parametri di deployment

Questa sezione descrive come configurare i valori dei parametri di deployment che verranno applicati al manifest Kubernetes, al servizio Cloud Run o al modello Helm.

Oltre a configurare le coppie chiave-valore, devi aggiungere i segnaposto al manifest, come descritto in questa sezione.

Aggiungere segnaposto al manifest

Nel manifest Kubernetes (per GKE) o nel servizio YAML (per Cloud Run), aggiungi segnaposto per tutti i valori da sostituire dopo il rendering.

Sintassi

Per le release che non utilizzano il renderer Helm con Skaffold, utilizza la seguente sintassi per i segnaposto:

[PROPERTY]: [DEFAULT_VALUE] # from-param: ${VAR_NAME}

In questa riga...

  • PROPERTY:

    È la proprietà di configurazione nel manifest Kubernetes o nel servizio YAML del servizio Cloud Run.

  • DEFAULT_VALUE

    È un valore da utilizzare se non vengono forniti valori per questa proprietà nella riga di comando, nella pipeline o nella configurazione di destinazione.

  • # from-param:

    Utilizza un carattere di commento per attivare l'istruzione deploy-parameters di Cloud Deploy, mentre from-param: indica a Cloud Deploy che segue un segnaposto deploy-parameters.

  • ${VAR_NAME}

    È il segnaposto da sostituire. Deve corrispondere alla chiave di una coppia chiave-valore fornita nella pipeline di distribuzione o nella configurazione di destinazione oppure al momento della creazione della release.

Parametri per i valori del grafico Helm

Se esegui il rendering di un grafico Helm che accetta valori di configurazione e vuoi impostare questi valori utilizzando parametri di deployment, i parametri di deployment devono avere nomi corrispondenti ai valori della configurazione Helm che vuoi impostare. Tutti i parametri di deployment vengono passati a Helm come argomenti --set al momento del rendering, senza dover modificare i valori di skaffold.yaml.

Ad esempio, se skaffold.yaml installa un grafico Helm che utilizza un parametro di configurazione webserver.port per specificare la porta da cui verrà avviato il server web e vuoi impostarlo in modo dinamico da un parametro di deployment, devi creare un parametro di deployment con il nome webserver.port con il valore che vuoi per la porta del server web.

Pertanto, se non fai solo riferimento ai modelli Helm nel tuo skaffold.yaml, ma li stai anche creando, puoi utilizzare la sintassi standard della variabile Helm {{ .Values.VAR_NAME }} nei tuoi modelli Helm.

Ad esempio, se abbiamo configurato un parametro di deployment webserver.port, potremmo utilizzarlo in questo modo:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webserver
spec:
  replicas: 3
  selector:
    matchLabels:
      app: webserver
  template:
    metadata:
      labels:
        app: webserver
    spec:
      containers:
      - name: webserver
        image: gcr.io/example/webserver:latest
        ports:
        - containerPort: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.
          name: web
        env:
        - name: WEBSERVER_PORT
          value: {{ .Values.webserver.port }} # replaced by deploy parameter `webserver.port`.

Aggiungi un parametro alla fase della pipeline

Puoi aggiungere coppie chiave-valore a una fase dell'avanzamento della pipeline di distribuzione. Questo è utile per i deployment paralleli, in modo da distinguere i target figlio.

  1. Aggiungi i segnaposto al manifest di Kubernetes o al servizio Cloud Run, come descritto qui.

    Ecco un esempio:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 replicas: 1 # from-param: ${deploy_replicas}
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2
       ports:
       - containerPort: 80

  2. Configura la pipeline di distribuzione in modo da includere deployParameters per la fase applicabile.

    Il codice YAML seguente è la configurazione per una fase della pipeline la cui destinazione è a target multiplo, che in questo caso ha due destinazioni figlio:

    serialPipeline:
 stages:
   - targetId: dev
     profiles: []
   - targetId: prod  # multi-target
     profiles: []
     deployParameters:
       - values:
           deploy_replicas: 1
           log_level: "NOTICE"
         matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
           my-app: "post-render-config-1"
       - values:
           deploy_replicas: 2
           log_level: "WARNING"
         matchTargetLabels: # optional, applies to all resources if unspecified; AND'd
           my-app: "post-render-config-2"

    In questa configurazione della pipeline di distribuzione, la stanza deployParameters include due values, ciascuno dei quali ha quanto segue:

    • Il nome della variabile, che ha lo stesso nome della variabile impostata nel file manifest

    • Un valore per quella variabile

    • Una o più etichette (facoltative) da abbinare a etichette specifiche per il target

      Se non specifichi un'etichetta, in una stanza matchTargetLabels il valore viene utilizzato per tutti i target nella fase.

  3. Se hai incluso matchTargetLabels , devi anche includere le etichette nelle destinazioni, affinché corrispondano. In questo modo, puoi identificare il valore da assegnare al target figlio.

    La destinazione deve corrispondere a tutte le etichette impostate nella stanza values.

    Se ometti matchTargetLabels, il valore values impostato nella pipeline viene applicato a tutti i target figlio. Tuttavia, se imposti più di un valore per lo stesso parametro, la release non andrà a buon fine.

Dopo il rendering di ogni manifest, Cloud Deploy aggiunge il valore per ogni variabile al manifest visualizzato.

Aggiungi un parametro alla configurazione di destinazione

Puoi aggiungere coppie chiave-valore a un target. Se utilizzi parametri di deployment per distinguere tra più target figlio, configurali nelle destinazioni secondarie, non in quelle dei target multipli.

  1. Configura il manifest Kubernetes o la definizione del servizio Cloud Run utilizzando un parametro al posto del valore che vuoi impostare al momento del deployment.

    Ecco un esempio:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2
       env:
       - name: envvar1
         value: example1 # from-param: ${application_env1}
       - name: envvar2
         value: example2 # from-param: ${application_env2}

    In questo manifest, il parametro envvar1 è impostato sul valore predefinito di example1, mentre il valore predefinito per envvar2 è example2.

  2. Configura i tuoi target in modo da includere deployParameters.

    Per ogni parametro che includi, devi identificare quanto segue:

    • Il nome della chiave, che corrisponde al nome della chiave (variabile) impostato nel manifest.

    • Un valore per quella chiave. Se non specifichi un valore, viene utilizzato il valore predefinito impostato nel manifest.

    Il codice YAML seguente è la configurazione di due target. Ogni target include una stanza deployParameters che imposta un valore. Ogni target include anche un'etichetta da associare ai parametri di deployment configurati in una fase della pipeline.

    apiVersion: deploy.cloud.google.com/v1beta1
kind: Target
metadata:
  name: prod1
  labels:
    my-app: "post-render-config-1"
description: development cluster
deployParameters:
  application_env1: "newValue1"
---

apiVersion: deploy.cloud.google.com/v1beta1
kind: target
metadata:
  name: prod2
  labels:
    my-app: "post-render-config-2"
description: development cluster
deployParameters:
  application_env1: "newValue2"

Quando viene creata la release, ma dopo il rendering dei manifest, Cloud Deploy aggiunge questi valori ai manifest sottoposti a rendering se includono le chiavi associate.

Passare un parametro al momento della creazione della release

Per trasmettere parametri e valori alla release:

  1. Configura il manifest Kubernetes o la definizione del servizio Cloud Run utilizzando un parametro al posto del valore che vuoi impostare al momento del deployment.

    Ecco un esempio:

    apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx-deployment
 labels:
   app: nginx
spec:
 selector:
   matchLabels:
     app: nginx
 template:
   metadata:
     labels:
       app: nginx
   annotations:
     commit: defaultShaValue # from-param: ${git-sha}
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2

    In questo esempio, l'SHA del commit è impostata come variabile denominata ${git-sha}. Il relativo valore viene trasmesso al momento della creazione della release utilizzando l'opzione --deploy-parameters=, come mostrato nel passaggio successivo.

    La sintassi di questa variabile è $ più il nome della variabile tra parentesi graffe. In questo esempio è ${git-sha}.

  2. Quando crei una release, includi l'opzione --deploy-parameters nel comando gcloud deploy releases create.

    --deploy-parameters prende un elenco separato da virgole di coppie chiave-valore, in cui la chiave è il segnaposto che hai aggiunto al file manifest.

    Il comando sarà simile a questo:

    gcloud deploy releases create test-release-001 \
--project=my-example-project \
--region=us-central1 \
--delivery-pipeline=my-params-demo-app-1 \
--images=my-app-image=gcr.io/google-containers/nginx@sha256:f49a843c290594dcf4d193535d1f4ba8af7d56cea2cf79d1e9554f077f1e7aaa \
--deploy-parameters="git-sha=f787cac"

Quando viene creata la release, ma dopo il rendering del manifest, Cloud Deploy fornisce i valori ai manifest sottoposti a rendering se includono le chiavi associate.

Visualizza tutti i parametri per una release

Puoi visualizzare i parametri impostati per una determinata release. Vengono visualizzati in una tabella nella pagina Dettagli della release e nella riga di comando (gcloud deploy releases describe).

  1. Nella pagina principale di Cloud Deploy, fai clic sulla pipeline di distribuzione che include la release che vuoi visualizzare.

  2. Nella pagina Dettagli sulla release, seleziona la scheda Artefatti.

Tutti i parametri di deployment impostati per questa release vengono mostrati in una tabella, con il nome e il valore della variabile in una colonna e il target o i target interessati nell'altra colonna.

Esegui il deployment di parametri e valori mostrati nella console Google Cloud

Passaggi successivi