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. Questa sostituzione viene eseguita dopo il rendering dei manifest, 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.

Tutto ciò che devi fare è includere i segnaposto nel manifest e impostare i valori per questi segnaposto nella pipeline di distribuzione o nella configurazione del target di Cloud Deploy oppure quando crei una release.

Questo articolo descrive come eseguire questa operazione.

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 di coppie chiave-valore post-rendering nel manifest.

Come funziona

I passaggi seguenti 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.

      Esistono tre modi per farlo, descritti qui.

  2. Quando crei una release, il manifest viene sottoposto a rendering.

    Se inizi con un manifest basato su modello, i valori vengono applicati ora alle variabili del modello. Se inizi con un manifest non elaborato, 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.

    La procedura di rendering ha già applicato i valori ai modelli di manifest, sostituendo alcuni valori e aggiungendo etichette specifiche di 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 del target per eseguire il deployment dell'applicazione.

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

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 al target rappresentato 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 del target stesso. Questo metodo ti consente di sostituire un valore per questo 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 è 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 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ù posizioni, ma con valori diversi, il comando gcloud deploy releases create non riesce e restituisce un errore.

In che cosa si differenzia dai modelli di manifest

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

Tecnica Minuto di sostituzione Applicabile a
Modello di 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)
Nel target Post-rendering Tutte le release; target specifico

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

Limitazioni

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

  • Un target secondario può inoltre ereditare fino a 50 parametri dal target multiplo principale, 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 è quando utilizzi un parametro di deployment come variabile di ambiente in un target personalizzato, devi utilizzare una barra tra la parola chiave customTarget e il nome della variabile (customTarget/VAR_NAME). Consulta Input e output obbligatori per la sintassi supportata.

  • 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 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 passati per convenzione.

Configurare i parametri di deployment

Questa sezione descrive come configurare i valori dei parametri di deployment che verranno applicati al manifest di 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 di Kubernetes (per GKE) o nel file YAML del servizio (per Cloud Run), aggiungi i 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 di 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 configurazione della pipeline o del target. 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. Questo deve corrispondere alla chiave di una coppia chiave-valore fornita nella pipeline di distribuzione o nella configurazione del target 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ù origini. Nell'esempio precedente, ${artifactRegion} verrebbe probabilmente definito nel target o nella fase della pipeline di distribuzione, mentre ${imageSha} verrebbe 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 impostare questi valori utilizzando i parametri di deployment, i parametri di deployment devono avere nomi che corrispondono ai valori di configurazione di Helm che vuoi impostare. Tutti i parametri di deployment vengono passati a Helm come --set argomenti al tempo di rendering, senza che sia necessaria alcuna modifica di skaffold.yaml

Ad esempio, se skaffold.yaml installa 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, dovrai 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 riferimento solo ai modelli Helm in skaffold.yaml, ma li crei anche, puoi utilizzare la sintassi standard delle variabili Helm di {{ .Values.VAR_NAME }} nei 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 distribuzione. Questa opzione è utile per i deployment paralleli, per distinguere tra i target secondari.

  1. Aggiungi i segnaposto al manifest di Kubernetes o al servizio Cloud Run service, 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 della pipeline applicabile.

    Il seguente file YAML è la configurazione per 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 è lo stesso nome della variabile impostata nel manifest

    • Un valore per questa variabile

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

      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 le etichette nei target per farle corrispondere. In questo modo, identifichi il valore da assegnare a quale target secondario.

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

    Se ometti matchTargetLabels, i 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 riuscirà.

Dopo il rendering di ogni manifest, Cloud Deploy aggiunge il valore di ogni variabile al manifest di cui è stato eseguito il rendering.

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 la definizione del manifest di Kubernetes o 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 tuoi target in modo da includere deployParameters.

    Per ogni parametro che includi, identifichi quanto segue:

    • Il nome della chiave, che è lo stesso nome della chiave (variabile) impostata nel manifest.

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

    Il seguente file 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.

Passare un parametro al momento della creazione della release

Segui questi passaggi per passare i parametri e i valori alla release:

  1. Configura la definizione del manifest di Kubernetes o 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 questa variabile viene passato al momento della creazione della release, utilizzando l'opzione --deploy-parameters=, come mostrato nel passaggio successivo.

    La sintassi per 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 di cui è stato eseguito il rendering se includono le chiavi associate.

Parametri di deployment con target personalizzati

Puoi utilizzare qualsiasi parametro di deployment come variabile di ambiente in target personalizzati. In questo caso, utilizza la sintassi specificata per target personalizzati.

I parametri di deployment destinati a essere 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 esso come CLOUD_DEPLOY_customTarget_vertexAIModel.

Parametri di deployment con hook di deployment

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

Parametri di deployment con verifica del deployment

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

Visualizzare tutti i parametri per una release

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

  1. Dalla 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 visualizzati nella console Google Cloud

Passaggi successivi