Pasa parámetros a tu implementación

Con Cloud Deploy, puedes pasar parámetros para tu versión, y esos valores se proporcionan al manifiesto o manifiestos antes de que se apliquen a sus respectivos destinos. Esta sustitución se realiza después de que los manifiestos se renderizan, como paso final de la operación de renderización de Cloud Deploy. Los valores se proporcionan a todos los manifiestos identificados en tu archivo skaffold.yaml que contienen los marcadores de posición correspondientes.

Todo lo que debes hacer es incluir marcadores de posición en tu manifiesto y establecer los valores para esos marcadores de posición en tu canalización de entrega de Cloud Deploy, en la configuración de destino o cuando crees una versión.

En este artículo, se explica cómo hacerlo.

¿Por qué usar parámetros de implementación?

Un uso típico de esto sería aplicar diferentes valores a manifiestos para objetivos diferentes en una implementación en paralelo. Sin embargo, puedes usar parámetros de implementación para todo lo que requiera la sustitución de pares clave-valor después de la renderización en tu manifiesto.

Cómo funciona

En los siguientes pasos, se describe el proceso general para configurar los parámetros de despliegue y proporcionar valores:

  1. Puedes configurar la parametrización de la implementación como se describe aquí.

    Estos son algunos de ellos:

    • Agrega los marcadores de posición a tu manifiesto.

    • Agrega valores para esos marcadores de posición.

      Existen tres maneras de hacerlo, que se describen aquí.

  2. Cuando creas una versión, se renderiza tu manifiesto.

    Si comienzas con un manifiesto con plantillas, los valores ahora se aplican a las variables de la plantilla. Si comienzas con un manifiesto sin procesar, este no se modificará. Skaffold realiza esta renderización.

    Sin embargo, puedes tener variables adicionales en tu manifiesto para las que los valores no se aplican en el momento de la renderización. Estos son los parámetros de implementación que se describen en este documento.

    Cuando se crea la versión, todos los parámetros de implementación se compilan en un diccionario, que se usa para reemplazar valores antes de que se apliquen los manifiestos.

  3. Después de la renderización, Cloud Deploy sustituye los valores de los parámetros de implementación.

    Estos son los valores que configuraste en el primer paso.

    El proceso de renderización ya aplicó valores a las plantillas de manifiesto, reemplazó algunos valores y agregó etiquetas específicas para Cloud Deploy. Sin embargo, los valores de estos parámetros de implementación se sustituyen después de la renderización. Las diferencias entre las plantillas de manifiesto y los parámetros de implementación se describen aquí.

  4. El manifiesto se aplica al entorno de ejecución de destino para implementar tu aplicación.

    Esto incluye los valores reemplazados en el tiempo de renderización y los valores de cualquier parámetro de implementación.

Diferentes formas de pasar valores

Puedes proporcionar parámetros y valores para esos parámetros de tres maneras:

  • En la definición de la canalización de entrega

    Proporcionas el parámetro y su valor en la definición de una etapa en la progresión de la canalización de publicación. El parámetro se pasa al objetivo representado por esa etapa. Si esa etapa hace referencia a un destino múltiple, los valores establecidos aquí se usan para todos los destinos secundarios.

    Este método te permite reemplazar un valor para todas las versiones de una canalización determinada para todos los destinos afectados. Los parámetros definidos para una etapa identifican una etiqueta, y el objetivo correspondiente para esa etapa debe tener una etiqueta coincidente.

  • En la definición del objetivo

    El parámetro y su valor se configuran en la definición del objetivo. Este método te permite reemplazar un valor para ese objetivo en todas las versiones.

  • En la línea de comandos, cuando creas una versión

    Incluye el parámetro y su valor con la marca --deploy-parameters en el comando gcloud deploy releases create.

    Este método te permite reemplazar un valor en el momento de la creación de la versión y aplicarlo a los manifiestos de todos los destinos afectados.

La configuración de estos se explica con más detalle aquí.

¿Puedo usar más de uno de estos métodos?

Sí, puedes incluir parámetros de implementación en la etapa de canalización, en la configuración de destino y en la línea de comandos. El resultado es que todos los parámetros se aceptan y se agregan al diccionario. Sin embargo, si se pasa un parámetro específico en más de un lugar, pero con valores diferentes, el comando gcloud deploy releases create falla con un error.

En qué se diferencia de las plantillas de manifiesto

Los parámetros de implementación, como se describe en este artículo, se distinguen de los marcadores de posición en un manifiesto con plantillas por la sintaxis. Sin embargo, si te preguntas por qué necesitas parámetros de implementación en lugar de usar solo las técnicas estándar para manifiestos con plantillas, en la siguiente tabla se muestran los diferentes propósitos:

Técnica Tiempo de sustitución Se aplica a
Plantilla de manifiesto Fase de renderización Versión específica; objetivo específico
En la línea de comandos Posrenderización Versión específica; todos los objetivos
En la canalización de entrega Posrenderización Todas las versiones; objetivos específicos (por etiqueta)
En el objetivo Posrenderización Todas las versiones; objetivo específico

En este documento, solo se abordan los parámetros de implementación (en la línea de comandos, la canalización y el objetivo), no los manifiestos con plantillas.

Limitaciones

  • Para cada tipo de parámetro, puedes crear un máximo de 25 parámetros.

  • Además, un destino secundario puede heredar hasta 25 parámetros de su destino múltiple superior, hasta un máximo de 100 parámetros en los destinos, incluidos los establecidos en la etapa de canalización.

  • El nombre de la clave tiene un límite de 63 caracteres y la siguiente expresión regular:

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

    Una excepción a esto es cuando usas un parámetro de implementación como una variable de entorno en un destino personalizado. En este caso, debes usar una barra diagonal entre la palabra clave customTarget y el nombre de la variable (customTarget/VAR_NAME). Consulta Entradas y salidas obligatorias para conocer la sintaxis admitida.

  • El prefijo CLOUD_DEPLOY_ está reservado y no se puede usar para un nombre de clave.

  • No puedes tener dos claves con el mismo nombre aplicadas al mismo objetivo.

  • El valor puede estar vacío, pero tiene un máximo de 512 caracteres.

  • Los marcadores de posición de los parámetros de implementación no se pueden usar para los valores de configuración de Helm, pero se deben pasar de acuerdo con la convención.

Configura los parámetros de implementación

En esta sección, se describe cómo configurar los valores de los parámetros de implementación que se aplicarán a tu manifiesto de Kubernetes, a tu servicio de Cloud Run o a tu plantilla de Helm.

Además de configurar esos pares clave-valor, debes agregar el marcador de posición o los marcadores de posición a tu manifiesto, como se describe en esta sección.

Agrega marcadores de posición a tu manifiesto

En tu manifiesto de Kubernetes (para GKE) o YAML de servicio (para Cloud Run), agregas marcadores de posición para los valores que deseas reemplazar después de la renderización.

Sintaxis

En el caso de las versiones que no usan el renderizador Helm con Skaffold, usa la siguiente sintaxis para tus marcadores de posición:

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

En esta línea…

  • PROPERTY:

    Es la propiedad de configuración en tu manifiesto de Kubernetes o en el archivo YAML del servicio de Cloud Run.

  • DEFAULT_VALUE

    Es un valor que se debe usar si no se proporcionan valores para esta propiedad en la línea de comandos, en la canalización o en la configuración de destino.

  • # from-param:

    Usa un carácter de comentario para activar la directiva deploy-parameters de Cloud Deploy, y from-param: le indica a Cloud Deploy que sigue un marcador de posición deploy-parameters.

  • ${VAR_NAME}

    Es el marcador de posición que se reemplazará. Debe coincidir con la clave de un par clave-valor proporcionado en la canalización de publicación o la configuración de destino, o bien cuando se crea la versión.

Parámetros para valores de gráficos de Helm

Si renderizas un gráfico de Helm que acepta valores de configuración y deseas establecer esos valores con parámetros de implementación, estos deben tener nombres que coincidan con los valores de configuración de Helm que deseas establecer. Todos los parámetros de implementación se pasan a Helm como argumentos --set en el momento de la renderización, sin necesidad de modificar tu skaffold.yaml.

Por ejemplo, si tu skaffold.yaml instala un gráfico de Helm que toma un parámetro de configuración de webserver.port para especificar en qué puerto se iniciará el servidor web y deseas configurarlo de forma dinámica desde un parámetro de implementación, deberás crear un parámetro de implementación con el nombre webserver.port con el valor que deseas para el puerto del servidor web.

Por lo tanto, si no solo haces referencia a plantillas de Helm en tu skaffold.yaml, sino que también las creas, puedes usar la sintaxis estándar de variables de Helm de {{ .Values.VAR_NAME }} en tus plantillas de Helm.

Por ejemplo, si tenemos configurado un parámetro de implementación de webserver.port, podríamos usarlo de la siguiente manera:

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`.

Agrega un parámetro a la etapa de canalización

Puedes agregar pares clave-valor a una etapa en la progresión de la canalización de publicación. Esto es útil para las implementaciones en paralelo, para distinguir entre los destinos secundarios.

  1. Agrega los marcadores de posición a tu manifiesto de Kubernetes o servicio de Cloud Run, como se describe aquí.

    A continuación, se presenta un ejemplo:

    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 tu canalización de entrega para que incluya deployParameters para la etapa de canalización aplicable.

    El siguiente YAML es la configuración de una etapa de canalización cuyo objetivo es un destino múltiple, que en este caso tiene dos destinos secundarios:

    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"

    En esta configuración de canalización de publicación, la estrofa deployParameters incluye dos values, cada una de las cuales tiene lo siguiente:

    • El nombre de la variable, que es el mismo que el de la variable que estableciste en el manifiesto

    • Un valor para esa variable

    • Una o más etiquetas (opcional) para que coincidan con las etiquetas específicas del objetivo

      Si no especificas una etiqueta, en una estrofa matchTargetLabels, ese valor se usa para todos los destinos de la etapa.

  3. Si incluiste matchTargetLabels, también debes incluir etiquetas en los destinos para que coincidan. De esta manera, identificarás qué valor asignar a qué objetivo secundario.

    El objetivo debe coincidir con todas las etiquetas establecidas en la estrofa values.

    Si omites matchTargetLabels, el values que configuraste en la canalización se aplica a todos los destinos secundarios. Sin embargo, si estableces más de un valor para el mismo parámetro, la versión fallará.

Después de que se renderiza cada manifiesto, Cloud Deploy agrega el valor de cada variable al manifiesto renderizado.

Agrega un parámetro a la configuración objetivo

Puedes agregar pares clave-valor a un objetivo. Si usas parámetros de implementación para distinguir entre varios destinos secundarios, configúralos en esos destinos secundarios, no en el destino múltiple.

  1. Configura tu manifiesto de Kubernetes o la definición del servicio de Cloud Run con un parámetro en lugar del valor que deseas establecer en el momento de la implementación.

    A continuación, se presenta un ejemplo:

    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}

    En este manifiesto, el parámetro envvar1 se establece en example1 de forma predeterminada y envvar2 en example2.

  2. Configura tus segmentaciones para incluir deployParameters.

    Para cada parámetro que incluyas, identifica lo siguiente:

    • El nombre de la clave, que es el mismo que el de la clave (variable) que estableciste en el manifiesto.

    • Un valor para esa clave. Si no proporcionas un valor, se usa el valor predeterminado establecido en el manifiesto.

    El siguiente YAML es la configuración de dos destinos. Cada objetivo incluye una estrofa deployParameters que establece un valor. Cada destino también incluye una etiqueta que debe coincidir con los parámetros de implementación configurados en una etapa de canalización.

    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"

Cuando se crea la versión, pero después de que se renderizan los manifiestos, Cloud Deploy agrega estos valores a los manifiestos renderizados si incluyen las claves asociadas.

Pasa un parámetro cuando se crea la versión

Sigue estos pasos para pasar parámetros y valores a la versión:

  1. Configura tu manifiesto de Kubernetes o la definición del servicio de Cloud Run con un parámetro en lugar del valor que deseas establecer en el momento de la implementación.

    A continuación, se presenta un ejemplo:

    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

    En este ejemplo, el SHA de confirmación se establece como una variable llamada ${git-sha}. Se pasa un valor para esto cuando se crea la versión con la opción --deploy-parameters=, como se ve en el siguiente paso.

    La sintaxis de esta variable es $ más el nombre de la variable entre llaves. En este ejemplo, es ${git-sha}.

  2. Cuando crees una versión, incluye la opción --deploy-parameters en el comando gcloud deploy releases create.

    --deploy-parameters toma una lista de pares clave-valor separados por comas, en la que la clave es el marcador de posición que agregaste al manifiesto.

    El comando se verá de la siguiente manera:

    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"

Cuando se crea la versión, pero después de la renderización del manifiesto, Cloud Deploy proporciona los valores a los manifiestos renderizados si incluyen las claves asociadas.

Implementa parámetros con objetivos personalizados

Puedes usar cualquier parámetro de implementación como variable de entorno en los objetivos personalizados. Cuando lo hagas, usa la sintaxis especificada para los objetivos personalizados.

Los parámetros de implementación destinados a ser entradas para objetivos personalizados pueden comenzar con customTarget/, por ejemplo, customTarget/vertexAIModel. Si usas este prefijo, usa la siguiente sintaxis cuando hagas referencia a un parámetro de implementación como una variable de entorno:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

En el que VAR_NAME es el nombre que sigue a la barra en el nombre del parámetro de implementación. Por ejemplo, si defines un parámetro de implementación llamado customTarget/vertexAIModel, haz referencia a él como CLOUD_DEPLOY_customTarget_vertexAIModel.

Implementa parámetros con hooks de implementación

Puedes usar cualquier parámetro de implementación como variable de entorno en los hooks de implementación.

Implementa parámetros con verificación de implementación

Puedes usar cualquier parámetro de implementación como una variable de entorno en la verificación de implementación.

Cómo ver todos los parámetros de una versión

Puedes ver los parámetros que se configuraron para una versión determinada. Se muestran en una tabla en la página Detalles de la versión y en la línea de comandos (gcloud deploy releases describe).

  1. En la página principal de Cloud Deploy, haz clic en la canalización de entrega que incluye la versión que deseas ver.

  2. En la página Detalles de la versión, selecciona la pestaña Artefactos.

Todos los parámetros de implementación que se configuraron para esta versión se muestran en una tabla, con el nombre y el valor de la variable en una columna, y el objetivo o los objetivos afectados en la otra.

parámetros de implementación y valores que se muestran en la consola de Google Cloud

¿Qué sigue?