Passare parametri al deployment

Con Cloud Deploy puoi passare i parametri per la release e questi valori vengono forniti al manifest o ai manifest prima che vengano applicati ai rispettivi target. Questa sostituzione viene eseguita dopo che i manifest sono stati eseguiti, come passaggio finale dell'operazione di rendering di Cloud Deploy. I valori vengono forniti a 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 importazione di Cloud Deploy o nella configurazione del target oppure quando crei una release.

Questo articolo spiega come fare.

Perché utilizzare i parametri di deployment?

Un utilizzo tipico è l'applicazione di valori diversi ai manifest per diversi target in un deployment parallelo. Tuttavia, puoi utilizzare i parametri di deployment per qualsiasi elemento che richieda la sostituzione della coppia chiave-valore post-rendering nel manifest.

Come funziona

I passaggi riportati di seguito descrivono la procedura generale per configurare i parametri di deployment e fornire i valori:

  1. Configura la parametrizzazione del deployment come descritto qui.

    È incluso quanto segue:

    • Aggiungi i segnaposto al manifest.

    • Aggiungi i valori per i segnaposto.

      Puoi procedere in tre modi, descritti qui.

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

    Se inizi con un manifest basato su modello, ora i valori vengono applicati alle variabili del modello. Se inizi con un manifest non elaborato, questo rimarrà invariato. Questo rendering viene eseguito da Skaffold.

    Tuttavia, puoi avere altre variabili nel file 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 per i parametri di deployment.

    Questi sono i valori configurati nel primo passaggio.

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

  4. Il file 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 di eventuali parametri di deployment

Diversi modi per passare i valori

Puoi fornire i parametri e i relativi valori in tre modi:

  • Nella definizione della pipeline di distribuzione

    Fornisci il parametro e il relativo valore nella definizione di una fase della progressione della pipeline di importazione. Il parametro viene passato al target rappresentato dalla fase. Se questa fase fa riferimento a un target multiplo, i valori impostati qui vengono utilizzati per tutti i target secondari.

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

  • Nella definizione del target

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

  • Nella riga di comando, quando crei una release

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

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

La configurazione di questi elementi è spiegata più nel dettaglio qui.

Posso utilizzare più di uno di questi metodi?

Sì, puoi includere i parametri di deployment nella fase della pipeline, nella configurazione del target 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ù di un punto, ma con valori diversi, il comando gcloud deploy releases create non va a buon fine e viene visualizzato un errore.

Qual è la differenza rispetto ai modelli manifest

I parametri di deployment, come descritti in questo articolo, si distinguono dai segnaposto in un manifest basato su modello per la sintassi. Tuttavia, se ti stai chiedendo perché ti servano i parametri di deployment anziché utilizzare semplicemente le tecniche standard per i manifest basati su modelli, la tabella seguente mostra i diversi scopi:

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

Questo documento riguarda solo i parametri di deployment (riga di comando, pipeline e target), non i manifest con modello.

Limitazioni

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

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

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

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

    Un'eccezione a questa regola è quando utilizzi un parametro di deployment come variabile di ambiente in un target personalizzato. In questo caso, devi utilizzare una barra tra la parola chiave customTarget e il nome della variabile (customTarget/VAR_NAME). Consulta Input e output richiesti per 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 allo stesso target.

  • Il valore può essere vuoto, ma ha un massimo di 512 caratteri.

  • I segnaposto dei parametri di deployment non possono essere utilizzati per i valori di configurazione di 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 queste coppie chiave-valore, devi aggiungere il segnaposto o i segnaposto al manifest, come descritto in questa sezione.

Aggiungere segnaposto al manifest

Nel manifest Kubernetes (per GKE) o nel file YAML del servizio (per Cloud Run), aggiungi segnaposto per i valori che vuoi 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 file YAML del servizio Cloud Run.

  • DEFAULT_VALUE

    È un valore da utilizzare se non sono stati forniti valori per questa proprietà sulla riga di comando o nella configurazione della pipeline o del target.

  • # from-param:

    Utilizza un carattere di commento per separare la direttiva deploy-parameters di Cloud Deploy e 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 importazione o nella configurazione del target o alla creazione della release.

Parametri per i valori dei grafici Helm

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

Ad esempio, se skaffold.yaml sta installando un grafico Helm che utilizza un parametro di configurazione webserver.port per specificare la porta su 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 e il valore che preferisci per la porta del server web.

Pertanto, se non fai solo riferimento ai modelli Helm in skaffold.yaml, ma li crei anche, puoi utilizzare la sintassi standard delle variabili Helm di {{ .Values.VAR_NAME }} nei tuoi modelli Helm.

Ad esempio, se abbiamo configurato un parametro di deployment di webserver.port, potremmo utilizzarlo nel seguente 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`.

Aggiungere un parametro allo stage della pipeline

Puoi aggiungere coppie chiave-valore a una fase della progressione della pipeline di importazione. Questo è utile per i deployment paralleli, per distinguere tra i target secondari.

  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 importazione in modo da includere deployParameters per la fase della pipeline applicabile.

    Il seguente codice YAML è la configurazione di una fase della pipeline il cui target è un target multiplo, che in questo caso ha due target secondari:

    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 contiene quanto segue:

    • Il nome della variabile, che corrisponde al nome della variabile impostata nel manifest

    • Un valore per la variabile

    • (Facoltativo) Una o più etichette da confrontare con le etichette specifiche del target

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

  3. Se hai incluso matchTargetLabels, devi anche includere le etichette nei target per trovare una corrispondenza. In questo modo, identifichi il valore da assegnare a ciascun target secondario.

    Il target deve corrispondere a tutte le etichette impostate nella stanza values.

    Se ometti matchTargetLabels, i valori values impostati nella pipeline vengono applicati a tutti i target secondari. 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 di ogni variabile al manifest visualizzato.

Aggiungere un parametro alla configurazione del target

Puoi aggiungere coppie chiave-valore a un target. Se utilizzi i parametri di deployment per distinguere tra più target secondari, configurali su questi target secondari, non sul target multiplo.

  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 su un valore predefinito di example1 e envvar2 è impostato su un valore predefinito di example2.

  2. Configura i target in modo da includere deployParameters.

    Per ogni parametro incluso, identifica quanto segue:

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

    • Un valore per la chiave. Se non fornisci un valore, viene utilizzato il valore predefinito impostato nel file manifest.

    Il seguente codice YAML è la configurazione per 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 visualizzati se includono le chiavi associate.

Passare un parametro al momento della creazione della release

Per passare 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 è impostato come variabile denominata ${git-sha}. Un valore per questo viene passato 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 accetta un elenco separato da virgole di coppie chiave-valore, dove la chiave è il segnaposto che hai aggiunto al manifest.

    Il comando sarà simile al seguente:

    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 visualizzati se includono le chiavi associate.

Esegui il deployment dei parametri con target personalizzati

Puoi utilizzare qualsiasi parametro di deployment come variabile di ambiente nei target personalizzati. A questo scopo, utilizza la sintassi specificata per i target personalizzati.

I parametri di deployment destinati come input per i target personalizzati possono iniziare con customTarget/, ad esempio customTarget/vertexAIModel. Se utilizzi questo prefisso, utilizza la seguente sintassi quando fai riferimento a un parametro di deployment come variabile di ambiente:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

dove VAR_NAME è il nome che segue la barra nel nome del parametro di deployment. Ad esempio, se definisci un parametro di deployment denominato customTarget/vertexAIModel, fai riferimento a CLOUD_DEPLOY_customTarget_vertexAIModel.

Parametri di deployment con hook di deployment

Puoi utilizzare qualsiasi parametro di deployment come variabile di ambiente nei hook di deployment.

Parametri di deployment con verifica del deployment

Puoi utilizzare qualsiasi parametro di deployment come variabile di ambiente nella verifica del deployment.

Visualizza tutti i parametri di una release

Puoi visualizzare i parametri impostati per una determinata release. Vengono visualizzati in una tabella nella pagina Dettagli della release e sulla 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 release, seleziona la scheda Artefatti.

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

parametri e valori di deployment mostrati nella console Google Cloud

Passaggi successivi