Transferir parámetros a tu implementación

Con Cloud Deploy, puede transferir parámetros de su lanzamiento, y esos valores se proporcionan al manifiesto o a los manifiestos antes de que se apliquen a sus respectivos destinos. Esta sustitución se realiza después de que se rendered los manifiestos, como paso final de la operación de renderización de Cloud Deploy. Se proporcionan valores a todos los manifiestos identificados en el archivo skaffold.yaml que contengan los marcadores de posición correspondientes.

Solo tiene que incluir marcadores de posición en su archivo de manifiesto y definir los valores de esos marcadores en su canalización de distribución de Cloud Deploy o en la configuración de destino, o bien al crear una versión.

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

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

Un uso habitual de esta función sería aplicar diferentes valores a los manifiestos de distintos destinos en una implementación paralela. Sin embargo, puedes usar parámetros de implementación para cualquier elemento que requiera la sustitución de pares clave-valor después del renderizado en tu manifiesto.

Cómo funciona

En los pasos siguientes se describe el proceso general para configurar los parámetros de implementación y proporcionar valores:

  1. Configura la parametrización de la implementación, tal como se describe aquí.

    En otros, se incluyen problemas relacionados con lo siguiente:

    • Añada los marcadores de posición al archivo de manifiesto, incluido un valor predeterminado para cada uno.

    • Añade valores para esos marcadores de posición.

      Hay tres formas de hacerlo, que se describen aquí.

  2. Cuando creas una versión, el manifiesto se rendered.

    Si empiezas con un archivo de manifiesto basado en una plantilla, los valores se aplican ahora a las variables de la plantilla. Si empiezas con un archivo de manifiesto sin procesar, no se modificará. Skaffold se encarga de este renderizado.

    Sin embargo, puedes tener variables adicionales en tu manifiesto cuyos valores no se apliquen en el tiempo de renderización. Estos son los parámetros de implementación que se describen en este documento.

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

  3. Una vez renderizados, Cloud Deploy sustituye los valores de los parámetros de despliegue.

    Estos son los valores que ha configurado en el primer paso.

    El proceso de renderización ya ha aplicado valores a las plantillas de manifiesto, ha sustituido algunos valores y ha añadido etiquetas específicas de Cloud Deploy. Sin embargo, los valores de estos parámetros de despliegue 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 tiempo de ejecución de destino para implementar tu aplicación.

    Esto incluye los valores sustituidos en el momento de la renderización y los valores de los parámetros de implementación.

Diferentes formas de transferir valores

Puede proporcionar parámetros y valores para esos parámetros de tres formas:

  • En la definición del flujo de procesamiento de entrega

    Usted proporciona el parámetro y su valor en la definición de una fase del proceso de entrega. El parámetro se transfiere al destino representado por esa fase. Si esa fase hace referencia a un elemento de destino múltiple, los valores definidos aquí se usan para todos los elementos de destino secundarios.

    Este método te permite sustituir un valor en todas las versiones de una determinada canalización, así como en todos los destinos afectados. Los parámetros definidos para una fase identifican una etiqueta, y el destino correspondiente de esa fase debe tener una etiqueta coincidente.

  • En la definición del objetivo

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

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

    Para incluir el parámetro y su valor, usa la marca --deploy-parameters en el comando gcloud deploy releases create.

    Este método le permite sustituir un valor en el momento de crear la versión y aplicar ese valor a los manifiestos de todos los destinos afectados.

La configuración de estos elementos 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 fase de la 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 añaden 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 y se produce un error.

¿En qué se diferencia de las plantillas de manifiesto?

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

Técnica Tiempo de sustitución Aplicable a
Plantilla de archivo de manifiesto Fase de renderización Lanzamiento específico; objetivo específico
En la línea de comandos Después del renderizado Lanzamiento específico; todos los objetivos
En el flujo de procesamiento de entrega Después del renderizado Todos los lanzamientos; segmentación específica (por etiqueta)
En el objetivo Después del renderizado Todos los lanzamientos; objetivo específico

Este documento trata solo sobre los parámetros de implementación (en la línea de comandos, la canalización y el destino), no sobre los manifiestos con plantilla.

Limitaciones

  • Por cada tipo de parámetro, puedes crear un máximo de 50 parámetros.

  • Además, un elemento de destino secundario puede heredar hasta 50 parámetros de su elemento de destino múltiple superior, hasta un máximo de 200 parámetros en los elementos de destino, incluidos los definidos en la fase de la canalización.

  • El nombre de la clave puede tener 63 caracteres como máximo y debe cumplir la siguiente expresión regular:

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

    La única excepción es cuando se usa un parámetro de implementación como variable de entorno en un destino personalizado. En ese caso, debe usar una barra entre la palabra clave customTarget y el nombre de la variable (customTarget/VAR_NAME). Consulte la sección Entradas y salidas obligatorias para ver la sintaxis admitida.

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

  • No puedes aplicar dos claves con el mismo nombre al mismo destino.

  • 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, sino que se deben transferir por convención.

Configurar 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, debe añadir los marcadores de posición a su archivo de manifiesto, tal como se describe en esta sección.

Añadir marcadores de posición al archivo de manifiesto

En el manifiesto de Kubernetes (para GKE) o en el archivo YAML de servicio (para Cloud Run), añade marcadores de posición para los valores que quieras sustituir después de renderizar.

Sintaxis

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

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

En esta línea...

  • PROPERTY:

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

  • DEFAULT_VALUE

    Es un valor que se debe usar si no se proporciona ningún valor para esta propiedad en la línea de comandos, en la canalización o en la configuración de destino. El valor predeterminado es obligatorio, pero puede ser una cadena vacía ("").

  • # from-param:

    Usa un carácter de comentario para activar la directiva deploy-parameters de Cloud Deploy. from-param: indica a Cloud Deploy que a continuación se incluye un marcador de posición deploy-parameters.

  • ${VAR_NAME}

    Es el marcador de posición que se va a sustituir. Debe coincidir con la clave de un par clave-valor proporcionado en la canalización de entrega o en la configuración de destino, o bien al crear la versión.

También puedes usar varios parámetros en una sola línea y usarlos como parte de una cadena más larga. Por ejemplo:

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

Estos parámetros pueden proceder de varias fuentes. En el ejemplo anterior, ${artifactRegion} probablemente se definiría en la fase de la canalización de destino o de entrega, mientras que ${imageSha} procedería de la línea de comandos en el momento de la creación de la versión.

Parámetros de los valores de los gráficos de Helm

Si renderizas un gráfico de Helm que acepta valores de configuración y quieres definir esos valores mediante parámetros de implementación, los parámetros de implementación deben tener nombres que coincidan con los valores de configuración de Helm que quieras definir. Todos los parámetros de implementación se transfieren a Helm como argumentos --set en el momento de la renderización, sin que sea necesario modificar tu skaffold.yaml.

Por ejemplo, si tu skaffold.yaml está instalando 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 quieres definirlo dinámicamente a partir de un parámetro de implementación, tendrás que crear un parámetro de implementación con el nombre webserver.port y el valor que quieras 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 utilizar la sintaxis de variables estándar de Helm de {{ .Values.VAR_NAME }} en tus plantillas de Helm.

Por ejemplo, si tenemos configurado un parámetro de implementación webserver.port, podemos utilizarlo 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`.

Añadir un parámetro a la fase del flujo de procesamiento

Puede añadir pares clave-valor a una fase de la progresión de la canalización de entrega. Esto resulta útil para las implementaciones paralelas, para distinguir entre los elementos secundarios de destino.

  1. Añade los marcadores de posición al manifiesto de Kubernetes o al servicio de Cloud Run, tal como se describe aquí.

    Veamos 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 flujo de procesamiento de entrega para que incluya deployParameters en la fase del flujo de procesamiento correspondiente.

    El siguiente archivo YAML es la configuración de una fase de una canalización cuyo destino 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 del flujo de procesamiento de entrega, la stanza deployParameters incluye dos values, cada una de las cuales tiene lo siguiente:

    • Nombre de la variable, que es el mismo que el de la variable que has definido en el manifiesto.

    • Un valor para esa variable

    • Una o varias etiquetas (opcional) que coincidan con las etiquetas específicas del objetivo

      Si no especifica una etiqueta en una estrofa matchTargetLabels, ese valor se utiliza para todos los destinos de la fase.

  3. Si ha incluido matchTargetLabels, también debe incluir etiquetas en los elementos de destino para que coincidan. De esta forma, identificas qué valor asignar a cada elemento secundario.

    El destino debe coincidir con todas las etiquetas definidas en la sección values.

    Si omite matchTargetLabels, el values que defina en la canalización se aplicará a todos los elementos secundarios. Sin embargo, si asigna más de un valor al mismo parámetro, la versión fallará.

Después de renderizar cada manifiesto, Cloud Deploy añade el valor de cada variable al manifiesto renderizado.

Añadir un parámetro a la configuración de destino

Puede añadir pares clave-valor a una segmentación. Si usas parámetros de implementación para distinguir entre varios elementos secundarios, configúralos en esos elementos, no en el elemento principal.

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

    Veamos 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 archivo de manifiesto, el parámetro envvar1 tiene el valor predeterminado example1 y envvar2 tiene el valor predeterminado example2.

  2. Configure sus objetivos para incluir deployParameters.

    En cada parámetro que incluyas, debes especificar lo siguiente:

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

    • Un valor para esa clave. Si no proporciona ningún valor, se usará el valor predeterminado definido en el manifiesto.

    El siguiente archivo YAML es la configuración de dos destinos. Cada objetivo incluye una estrofa deployParameters que define un valor. Cada destino también incluye una etiqueta que debe coincidir con los parámetros de implementación configurados en una fase de la 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 rendericen los manifiestos, Cloud Deploy añade estos valores a los manifiestos renderizados si incluyen las claves asociadas.

Transferir un parámetro al crear una versión

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

  1. Configura tu manifiesto de Kubernetes o tu definición de servicio de Cloud Run con un parámetro en lugar del valor que quieras definir en el momento del despliegue.

    Veamos 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 la confirmación se define como una variable llamada ${git-sha}. Este valor se transmite al crear el lanzamiento mediante la opción --deploy-parameters=, como se muestra en el paso siguiente.

    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, donde la clave es el marcador que añadió al manifiesto.

    El comando tendrá un aspecto similar a este:

    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 renderizar el manifiesto, Cloud Deploy proporciona los valores a los manifiestos renderizados si incluyen las claves asociadas.

Implementar parámetros con objetivos personalizados

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

Los parámetros que se van a usar como entradas para objetivos personalizados pueden empezar por customTarget/, como customTarget/vertexAIModel. Si usas este prefijo, utiliza la siguiente sintaxis cuando hagas referencia a un parámetro de implementación como variable de entorno:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

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

Desplegar parámetros con hooks de despliegue

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

Desplegar parámetros con la verificación de despliegues

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

Ver todos los parámetros de una versión

Puede ver los parámetros que se han definido para un lanzamiento concreto. 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 el flujo de procesamiento de entrega que incluya la versión que quieras 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 han definido para esta versión se muestran en una tabla, con el nombre y el valor de la variable en una columna y el destino o los destinos afectados en la otra.

Implementa los parámetros y los valores que se muestran en la consola Google Cloud .

Siguientes pasos