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:

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