Passare parametri al deployment

Utilizzando 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. rendered I valori vengono forniti a tutti i manifest identificati nel file skaffold.yaml che contengono i segnaposto corrispondenti.

Tutto ciò che devi fare è includere i segnaposto nel manifest e impostare i valori per questi segnaposto nella pipeline di distribuzione 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 target diversi in un deployment parallelo. Tuttavia, puoi utilizzare i parametri di deployment per qualsiasi elemento che richieda la sostituzione delle coppie chiave-valore post-rendering nel manifest.

Come funziona

I seguenti passaggi 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, incluso un valore predefinito per ciascuno.

    • Aggiungi i valori per questi segnaposto.

      Puoi farlo in tre modi, descritti qui.

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

    Se inizi con un manifest basato su un modello, i valori vengono applicati ora per le variabili del modello. Se inizi con un manifest grezzo, questo rimane invariato. Questo rendering viene eseguito da Skaffold.

    Tuttavia, puoi avere variabili aggiuntive 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 che vengano applicati i manifest.

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

    Questi sono i valori che hai configurato nel primo passaggio.

    Il processo di rendering ha già applicato i valori ai modelli di manifest, sostituendo alcuni valori e aggiungendo etichette specifiche per Cloud Deploy. ma 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 di tutti i parametri di distribuzione.

Diversi modi per passare i valori

Puoi fornire parametri e valori per questi parametri 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 distribuzione. Il parametro viene passato alla destinazione rappresentata da questa 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 quella fase deve avere un'etichetta corrispondente.

  • Nella definizione del target

    Configura il parametro e il relativo valore nella definizione della destinazione. Questo metodo ti consente di sostituire un valore per la destinazione per tutte le uscite.

  • Dalla 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 consente di sostituire un valore al momento della creazione della release, applicando questo valore ai manifest di tutti i target interessati.

La configurazione di questi elementi è 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 della 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ù di una posizione, ma con valori diversi, il comando gcloud deploy releases create non riesce e viene visualizzato un errore.

In che modo si differenziano dai modelli di manifest

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

Tecnica Tempo di sostituzione Applicabile a
Modello di manifest Fase di rendering Release specifica; target specifico
Nella riga di comando Post-rendering Release specifica; tutte le destinazioni
Nella pipeline di distribuzione Post-rendering Tutte le uscite; target specifici (per etichetta)
In linea con il target Post-rendering Tutte le uscite; target specifico

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

Limitazioni

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

  • Un target figlio può inoltre ereditare fino a 50 parametri dal target multiplo padre, fino a un massimo di 200 parametri nei target, 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 si verifica quando utilizzi un parametro di deployment come variabile di ambiente in una destinazione personalizzata. In questo caso, devi utilizzare una barra tra la parola chiave customTarget e il nome della variabile (customTarget/VAR_NAME). Per la sintassi supportata, consulta Input e output richiesti.

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

  • Non puoi avere due chiavi con lo stesso nome applicate allo stesso target.

  • Il valore può essere vuoto, ma può contenere 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 passati per convenzione.

Configurare 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 tutti 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 vengono forniti valori per questa proprietà nella riga di comando o nella pipeline o nella configurazione di destinazione. Il valore predefinito è obbligatorio, ma può essere una stringa vuota ("").

  • # from-param:

    Utilizza un carattere di commento per impostare 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 distribuzione o nella configurazione di destinazione oppure al momento della creazione della release.

Puoi anche utilizzare più parametri in una singola riga e utilizzarli come parte di una stringa più lunga, ad esempio:

image: my-image # from-param: ${artifactRegion}-docker.pkg.dev/my-project/my-repo/my-image@sha256:${imageSha}

Questi parametri possono provenire da più fonti. Nell'esempio precedente, ${artifactRegion} verrebbe probabilmente definito nella fase di destinazione o pipeline di distribuzione, mentre ${imageSha} deriverebbe dalla riga di comando 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 impostarli utilizzando i parametri di deployment, questi ultimi devono avere nomi che corrispondano ai valori di configurazione di Helm che vuoi impostare. Tutti i parametri di deployment vengono passati a Helm come argomenti --set in fase di rendering, senza alcuna modifica del tuo skaffold.yaml.

Ad esempio, se il tuo skaffold.yaml sta installando un grafico Helm che accetta 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 con il valore che vuoi per la porta del server web.

Pertanto, se non solo fai riferimento ai modelli Helm nel tuo 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 è configurato un parametro di deployment 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 alla fase della pipeline

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

  1. Aggiungi i segnaposto al manifest 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 che includa deployParameters per la fase della pipeline applicabile.

    Il seguente 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 sezione deployParameters include due values, ognuna delle quali ha quanto segue:

    • Il nome della variabile, che corrisponde a quello della variabile impostata nel manifest

    • Un valore per la variabile

    • Una o più etichette (facoltative) da confrontare con le etichette specifiche della destinazione

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

  3. Se hai incluso matchTargetLabels , devi anche includere etichette nei target, per abbinarli. In questo modo, identifichi quale valore assegnare a quale target secondario.

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

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

Dopo il rendering di ogni manifest, Cloud Deploy aggiunge il valore di ogni variabile al manifest sottoposto a rendering.

Aggiungere un parametro alla configurazione della destinazione

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 sul valore predefinito example1, mentre envvar2 è impostato sul valore predefinito example2.

  2. Configura i target in modo che includano deployParameters.

    Per ogni parametro che includi, identifica quanto segue:

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

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

    Il seguente YAML è la configurazione per due target. Ogni target include una sezione deployParameters che imposta un valore. Ogni target include anche un'etichetta, da abbinare 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 di cui è stato eseguito il rendering se includono le chiavi associate.

Trasferire un parametro durante la creazione della release

Segui questi passaggi 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, lo 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 di coppie chiave-valore separate da virgole, dove la chiave è il segnaposto che hai aggiunto al 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.

Eseguire il deployment dei parametri con target personalizzati

Puoi utilizzare qualsiasi parametro di deployment come variabile di ambiente nei target personalizzati. Quando lo fai, utilizza la sintassi specificata per i target personalizzati.

I parametri di deployment destinati a essere utilizzati 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 deploy. Ad esempio, se definisci un parametro di deployment denominato customTarget/vertexAIModel, fai riferimento a questo parametro come CLOUD_DEPLOY_customTarget_vertexAIModel.

Parametri di deployment con hook di deployment

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

Parametri di deployment con verifica del deployment

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

Visualizzare tutti i parametri di una release

Puoi visualizzare i parametri impostati per una determinata uscita. Vengono visualizzati in una tabella nella pagina Dettagli 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 la destinazione o le destinazioni interessate nell'altra colonna.

Parametri e valori di deployment visualizzati nella console Google Cloud

Passaggi successivi