Con Cloud Deploy, puedes pasar parámetros para tu versión, y esos valores se proporcionan al manifiesto o 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. 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 la canalización de entrega o la configuración del destino de Cloud Deploy, o bien cuando crees una versión.
En este artículo, se describe cómo hacerlo.
¿Por qué usar parámetros de implementación?
Un uso típico de esto sería aplicar diferentes valores a los manifiestos para diferentes 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 posteriores a la renderización en tu manifiesto.
Cómo funciona
En los siguientes pasos, se describe el proceso general para configurar los parámetros de implementación y proporcionar valores:
Configura la parametrización de la implementación, como se describe aquí.
Estas son algunas de ellas:
Agrega los marcadores de posición a tu manifiesto, incluido un valor predeterminado para cada uno.
Agrega valores para esos marcadores de posición.
Hay tres maneras de hacerlo, que se describen aquí.
Cuando creas una versión, se rendered tu manifiesto.
Si comienzas con un manifiesto basado en plantillas, ahora se aplican los valores para las variables de 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 no se aplican valores en el tiempo de renderización. Estos son los parámetros de implementación que se describen en este documento.
En el momento de la creación de la 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.
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 de 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í.
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 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 entrega. El parámetro se pasa al destino 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 todos los lanzamientos dentro de un canal determinado, 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.
-
Configuras el parámetro y su valor en la definición del objetivo en sí. Este método te permite reemplazar un valor para ese objetivo en todos los lanzamientos.
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 comandogcloud deploy releases create
.Este método te permite reemplazar un valor en el momento de la creación de la versión y aplicar ese valor a los manifiestos de todos los objetivos 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 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 agregan al diccionario. Sin embargo, si un parámetro específico se pasa 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 describen en este artículo, se distinguen de los marcadores de posición en un manifiesto basado en plantillas por su sintaxis. Sin embargo, si te preguntas por qué necesitarías parámetros de implementación en lugar de usar las técnicas estándar para los manifiestos basados en plantillas, la siguiente tabla muestra los diferentes propósitos:
Técnica | Hora de sustitución | Se aplica a |
---|---|---|
Plantilla de manifiesto | Fase de renderización | Versión específica y destino específico |
En la línea de comandos | Renderización posterior | Versión específica; todos los destinos |
En la canalización de entrega | Renderización posterior | Todos los lanzamientos y objetivos específicos (por sello discográfico) |
Dentro del objetivo | Renderización posterior | Todos los lanzamientos; destino específico |
Este documento solo trata sobre los parámetros de implementación (en la línea de comandos, la canalización y el destino), no sobre los manifiestos basados en plantillas.
Limitaciones
Para cada tipo de parámetro, puedes crear un máximo de 50 parámetros.
Además, un destino secundario puede heredar hasta 50 parámetros de su destino múltiple principal, con un máximo de 200 parámetros en los destinos, incluidos los establecidos en la etapa de la canalización.
El nombre de la clave tiene un límite de 63 caracteres y debe cumplir con 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 ese caso, debes usar una barra 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 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 pasar por 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 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 en el archivo YAML del servicio (para Cloud Run), agrega marcadores de posición para los valores que desees sustituir después de la renderización.
Sintaxis
Para 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 usa 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. El valor predeterminado es obligatorio, pero puede ser una cadena vacía (
""
).# from-param:
Usa un carácter de comentario para separar la directiva
deploy-parameters
de Cloud Deploy, yfrom-param:
le indica a Cloud Deploy que sigue un marcador de posicióndeploy-parameters
.${VAR_NAME}
Es el marcador de posición que se sustituirá. Debe coincidir con la clave de un par clave-valor proporcionado en la configuración del destino o la canalización de entrega, o bien en la creación de 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 provenir de varias fuentes. En el ejemplo anterior, ${artifactRegion}
probablemente se definiría en la etapa de destino o de canalización de entrega, mientras que ${imageSha}
provendría de la línea de comandos en el momento de la creación de la versión.
Parámetros para los valores del gráfico 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, los parámetros de implementación 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 establecerlo 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 desees para el puerto del servidor web.
Por lo tanto, si no solo haces referencia a las plantillas de Helm en tu skaffold.yaml
, sino que también las creas, puedes utilizar 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 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`.
Agrega un parámetro a la etapa de la canalización
Puedes agregar pares clave-valor a una etapa en la progresión de la canalización de entrega. Esto es útil para las implementaciones paralelas, ya que permite distinguir entre los destinos secundarios.
Agrega los marcadores de posición a tu manifiesto de Kubernetes o servicio de Cloud Run, como se describe aquí.
Por 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
Configura tu canalización de entrega para que incluya
deployParameters
en la etapa de canalización aplicable.El siguiente YAML es la configuración de una etapa de 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 de canalización de entrega, la sección
deployParameters
incluye dosvalues
, cada uno de los 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 sección
matchTargetLabels
, ese valor se usará para todos los destinos de la etapa.
Si incluiste
matchTargetLabels
, también debes incluir etiquetas en los destinos para que coincidan. De esta manera, identificas qué valor asignar a cada objetivo secundario.El destino debe coincidir con todas las etiquetas establecidas en la sección
values
.Si omites
matchTargetLabels
, elvalues
que establezcas en la canalización se aplicará a todos los destinos secundarios. Sin embargo, si estableces más de un valor para el mismo parámetro, fallará el lanzamiento.
Después de renderizar cada manifiesto, Cloud Deploy agrega el valor de cada variable al manifiesto renderizado.
Agrega un parámetro a la configuración del destino
Puedes agregar pares clave-valor a un destino. 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.
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.
Por 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 un valor predeterminado deexample1
yenvvar2
se establece en un valor predeterminado deexample2
.Configura tus objetivos para incluir
deployParameters
.Para cada parámetro que incluyas, identifica lo siguiente:
Es 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 usará el valor predeterminado establecido en el manifiesto.
El siguiente YAML es la configuración de dos destinos. Cada destino 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 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 renderizan los manifiestos, Cloud Deploy agrega estos valores a los manifiestos renderizados si incluyen las claves asociadas.
Pasa un parámetro en la creación de la versión
Sigue estos pasos para pasar parámetros y valores a la versión:
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.
Por 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 establece como una variable llamada
${git-sha}
. Se pasa un valor para este parámetro en la creación de la versión, con la opción--deploy-parameters=
, como se muestra en el siguiente paso.La sintaxis para esta variable es
$
más el nombre de la variable entre corchetes. En este ejemplo, es${git-sha}
.Cuando crees una versión, incluye la opción
--deploy-parameters
en el comandogcloud 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á 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 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 una variable de entorno en destinos personalizados. Cuando lo hagas, usa la sintaxis especificada para los objetivos personalizados.
Los parámetros de implementación que se usan como entradas para los 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]
Aquí 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 una variable de entorno en los enlaces 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 la implementación.
Cómo ver todos los parámetros de una versión
Puedes ver los parámetros que se configuraron para un lanzamiento determinado. 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
).
En la página principal de Cloud Deploy, haz clic en la canalización de entrega que incluye la versión que deseas ver.
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 destino o los destinos afectados en la otra columna.
¿Qué sigue?
Prueba la guía de inicio rápido: Usa parámetros de implementación.
Obtén más información para usar las implementaciones en paralelo.