Transmitir parâmetros para a implantação

Usando o Cloud Deploy, é possível transmitir parâmetros para a versão, e esses valores são fornecidos ao manifesto ou aos manifestos antes que eles sejam aplicados aos respectivos destinos. Essa substituição é feita depois que os manifestos são renderizados, como a etapa final na operação de renderização do Cloud Deploy. Os valores são fornecidos a todos os manifestos identificados no arquivo skaffold.yaml que contêm os marcadores correspondentes.

Basta incluir marcadores no manifesto e definir os valores desses marcadores no pipeline de entrega ou na configuração de destino do Cloud Deploy ou ao criar uma versão.

Este artigo descreve como fazer isso.

Por que usar parâmetros de implantação?

Um uso típico seria aplicar valores diferentes a manifestos para diferentes destinos em uma implantação paralela. No entanto, é possível usar parâmetros de implantação para qualquer coisa que exija a substituição de pares de chave-valor pós-renderização no manifesto.

Como funciona

As etapas a seguir descrevem o processo geral para configurar parâmetros de implantação e fornecer valores:

  1. Configure a parametrização de implantação, conforme descrito aqui.

    Isso inclui o seguinte:

    • Adicione os marcadores ao manifesto, incluindo um valor padrão para cada um.

    • Adicione valores para esses marcadores.

      Há três maneiras de fazer isso, descritas aqui.

  2. Quando você cria uma versão, o manifesto é renderizado.

    Se você começar com um manifesto com modelo, os valores serão aplicados agora para variáveis de modelo. Se você começar com um manifesto bruto, ele permanecerá inalterado. Essa renderização é feita pelo Skaffold.

    No entanto, é possível ter outras variáveis no manifesto para as quais os valores não são aplicados no tempo de renderização. Esses são os parâmetros de implantação descritos neste documento.

    Na criação da versão, todos os parâmetros de implantação são compilados em um dicionário, que é usado para substituir valores antes que os manifestos sejam aplicados.

  3. Após a renderização, o Cloud Deploy substitui os valores dos parâmetros de implantação.

    Esses são os valores configurados na primeira etapa.

    O processo de renderização já aplicou valores aos modelos de manifesto, substituindo alguns valores e adicionando rótulos específicos do Cloud Deploy. No entanto, os valores desses parâmetros de implantação são substituídos após a renderização. As diferenças entre modelos de manifesto e parâmetros de implantação são descritas aqui.

  4. O manifesto é aplicado ao ambiente de execução de destino para implantar o aplicativo.

    Isso inclui os valores substituídos no tempo de renderização e os valores de todos os parâmetros de implantação.

Diferentes maneiras de transmitir valores

É possível fornecer parâmetros e valores para esses parâmetros de três maneiras:

  • Na definição do pipeline de entrega

    Você fornece o parâmetro e o valor dele na definição de um estágio na progressão do pipeline de entrega. O parâmetro é transmitido ao destino representado por esse estágio. Se esse estágio fizer referência a um destino múltiplo, os valores definidos aqui serão usados para todos os destinos filhos.

    Esse método permite substituir um valor para todas as versões em um determinado pipeline, para todos os destinos afetados. Os parâmetros definidos para um estágio identificam um rótulo, e o destino correspondente para esse estágio precisa ter um rótulo correspondente.

  • Na definição de destino

    Você configura o parâmetro e o valor dele na definição do próprio destino. Esse método permite substituir um valor para esse destino em todas as versões.

  • Na linha de comando, ao criar uma versão

    Você inclui o parâmetro e o valor dele usando a flag --deploy-parameters no comando gcloud deploy releases create.

    Esse método permite substituir um valor no momento da criação da versão, aplicando esse valor aos manifestos de todos os destinos afetados.

A configuração deles é explicada com mais detalhes aqui.

Posso usar mais de um desses métodos?

Sim, é possível incluir parâmetros de implantação no estágio do pipeline, na configuração de destino e na linha de comando. O resultado é que todos os parâmetros são aceitos e adicionados ao dicionário. No entanto, se um parâmetro específico for transmitido em mais de um lugar, mas com valores diferentes, o comando gcloud deploy releases create falhará com um erro.

Qual é a diferença em relação aos modelos de manifesto

Os parâmetros de implantação, conforme descrito neste artigo, são diferenciados dos marcadores em um manifesto com modelo pela sintaxe. No entanto, se você estiver se perguntando por que precisaria de parâmetros de implantação em vez de apenas usar as técnicas padrão para manifestos com modelo, a tabela a seguir mostra as diferentes finalidades:

Técnica Tempo de substituição Aplicável a
Modelo de manifesto Fase de renderização Versão específica; destino específico
Na linha de comando Pós-renderização Versão específica; todos os destinos
No pipeline de entrega Pós-renderização Todas as versões; destinos específicos (por rótulo)
No destino Pós-renderização Todas as versões; destino específico

Este documento trata apenas de parâmetros de implantação (na linha de comando, no pipeline e no destino), não de manifestos com modelo.

Limitações

  • Para cada tipo de parâmetro, é possível criar um máximo de 50 parâmetros.

  • Um destino filho também pode herdar até 50 parâmetros do destino múltiplo pai, até um máximo de 200 parâmetros nos destinos, incluindo aqueles definidos no estágio do pipeline.

  • O nome da chave é limitado a um máximo de 63 caracteres e à seguinte expressão regular:

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

    Uma exceção a isso é quando você está usando um parâmetro de implantação como uma variável de ambiente em um destino personalizado. Nesse caso, é necessário usar uma barra entre a palavra-chave customTarget e o nome da variável (customTarget/VAR_NAME). Consulte Entradas e saídas necessárias para a sintaxe compatível.

  • O prefixo CLOUD_DEPLOY_ é reservado e não pode ser usado para um nome de chave.

  • Não é possível ter duas chaves com o mesmo nome aplicadas ao mesmo destino.

  • O valor pode estar vazio, mas tem um máximo de 512 caracteres.

  • Os marcadores de parâmetros de implantação não podem ser usados para valores de configuração do Helm, mas precisam ser transmitidos por convenção.

Configurar parâmetros de implantação

Esta seção descreve como configurar valores de parâmetros de implantação que serão aplicados ao manifesto do Kubernetes, ao serviço do Cloud Run ou ao modelo do Helm.

Além de configurar esses pares de chave-valor, é necessário adicionar o marcador ou os marcadores ao manifesto, conforme descrito nesta seção.

Adicionar marcadores ao manifesto

No manifesto do Kubernetes (para GKE) ou no YAML de serviço (para Cloud Run), adicione marcadores para todos os valores que você quer substituir após a renderização.

Sintaxe

Para versões que não estão usando o Helm renderizador com Skaffold, use a seguinte sintaxe para os marcadores:

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

Nesta linha...

  • PROPERTY:

    É a propriedade de configuração no manifesto do Kubernetes ou no YAML de serviço do Cloud Run.

  • DEFAULT_VALUE

    É um valor a ser usado se nenhum valor for fornecido para essa propriedade na linha de comando ou na configuração do pipeline ou de destino. O valor padrão é obrigatório, mas pode ser uma string vazia ("").

  • # from-param:

    Usa um caractere de comentário para definir a diretiva deploy-parameters do Cloud Deploy, e from-param: informa ao Cloud Deploy que um marcador deploy-parameters segue.

  • ${VAR_NAME}

    É o marcador a ser substituído. Ele precisa corresponder à chave de um par de chave-valor fornecido no pipeline de entrega ou na configuração de destino ou na criação da versão.

Também é possível usar vários parâmetros em uma única linha e usá-los como parte de uma string mais longa, por exemplo:

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

Esses parâmetros podem vir de várias fontes. No exemplo anterior, ${artifactRegion} provavelmente seria definido no destino ou no estágio do pipeline de entrega, enquanto ${imageSha} viria da linha de comando no momento da criação da versão.

Parâmetros para valores de gráfico do Helm

Se você estiver renderizando um gráfico do Helm que aceita valores de configuração, e quiser definir esses valores usando parâmetros de implantação, os parâmetros de implantação precisam ter nomes que correspondam aos valores de configuração do Helm que você quer definir. Todos os parâmetros de implantação são transmitidos ao Helm como --set argumentos no tempo de renderização, sem necessidade de modificar o skaffold.yaml necessário.

Por exemplo, se o skaffold.yaml estiver instalando um gráfico do Helm que usa um parâmetro de configuração de webserver.port para especificar em qual porta o servidor da Web será iniciado e você quiser definir isso dinamicamente a partir de um parâmetro de implantação, será necessário criar um parâmetro de implantação com o nome webserver.port com o valor desejado para a porta do servidor da Web.

Portanto, se você não estiver apenas referenciando modelos do Helm no skaffold.yaml, mas também criando-os, poderá usar a sintaxe de variável padrão do Helm de {{ .Values.VAR_NAME }} nos modelos do Helm.

Por exemplo, se tivermos um parâmetro de implantação de webserver.port configurado, poderemos usá-lo da seguinte maneira:

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

Adicionar um parâmetro ao estágio do pipeline

É possível adicionar pares de chave-valor a um estágio na progressão do pipeline de entrega. Isso é útil para implantações paralelas, para distinguir entre destinos filhos.

  1. Adicione os marcadores ao manifesto do Kubernetes ou ao serviço do Cloud Run, conforme descrito aqui.

    Veja um exemplo:

    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. Configure o pipeline de entrega para incluir deployParameters para o estágio de pipeline aplicável.

    O YAML a seguir é a configuração de um estágio de pipeline cujo destino é um destino múltiplo, que, nesse caso, tem dois destinos filhos:

    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"

    Nessa configuração de pipeline de entrega, a seção deployParameters inclui dois values, cada um com o seguinte:

    • O nome da variável, que é o mesmo nome da variável definida no manifesto

    • Um valor para essa variável

    • Um ou mais rótulos (opcional) para corresponder a rótulos específicos do destino

      Se você não especificar um rótulo em uma seção matchTargetLabels, esse valor será usado para todos os destinos no estágio.

  3. Se você incluiu matchTargetLabels, também é necessário incluir rótulos nos destinos para que eles correspondam. Dessa forma, você identifica qual valor atribuir a qual destino filho.

    O destino precisa corresponder a todos os rótulos definidos na seção values.

    Se você omitir matchTargetLabels, os values definidos no pipeline serão aplicados a todos os destinos filhos. No entanto, se você definir mais de um valor para o mesmo parâmetro, a versão falhará.

Depois que cada manifesto é renderizado, o Cloud Deploy adiciona o valor de cada variável ao manifesto renderizado.

Adicionar um parâmetro à configuração de destino

É possível adicionar pares de chave-valor a um destino. Se você estiver usando parâmetros de implantação para distinguir entre vários destinos filhos, configure-os nesses destinos filhos, não no destino múltiplo.

  1. Configure o manifesto do Kubernetes ou a definição de serviço do Cloud Run usando um parâmetro no lugar do valor que você quer definir no momento da implantação.

    Veja um exemplo:

    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}

    Nesse manifesto, o parâmetro envvar1 é definido como example1 e envvar2 é definido como example2.

  2. Configure os destinos para incluir deployParameters.

    Para cada parâmetro que você está incluindo, identifique o seguinte:

    • O nome da chave, que é o mesmo nome da chave (variável) definida no manifesto.

    • Um valor para essa chave. Se você não fornecer um valor, o valor padrão definido no manifesto será usado.

    O YAML a seguir é a configuração de dois destinos. Cada destino inclui uma seção deployParameters que define um valor. Cada destino também inclui um rótulo a ser correspondido com parâmetros de implantação configurados em um estágio de 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 a versão é criada, mas depois que os manifestos são renderizados, o Cloud Deploy adiciona esses valores aos manifestos renderizados se eles incluírem as chaves associadas.

Transmitir um parâmetro na criação da versão

Siga estas etapas para transmitir parâmetros e valores à versão:

  1. Configure o manifesto do Kubernetes ou a definição de serviço do Cloud Run usando um parâmetro no lugar do valor que você quer definir no momento da implantação.

    Veja um exemplo:

    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

    Neste exemplo, o SHA de confirmação é definido como uma variável chamada ${git-sha}. Um valor para isso é transmitido na criação da versão, usando a opção --deploy-parameters=, conforme mostrado na próxima etapa.

    A sintaxe dessa variável é $ mais o nome da variável entre chaves. Neste exemplo, é ${git-sha}.

  2. Ao criar uma versão, inclua a opção --deploy-parameters no comando gcloud deploy releases create.

    --deploy-parameters usa uma lista separada por vírgulas de pares de chave-valor, em que a chave é o marcador que você adicionou ao manifesto.

    O comando será semelhante 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"

Quando a versão é criada, mas após a renderização do manifesto, o Cloud Deploy fornece os valores aos manifestos renderizados se eles incluírem as chaves associadas.

Parâmetros de implantação com destinos personalizados

É possível usar qualquer parâmetro de implantação como uma variável de ambiente em destinos personalizados. Ao fazer isso, use a sintaxe especificada para destinos personalizados.

Os parâmetros de implantação destinados a entradas para destinos personalizados podem começar com customTarget/, por exemplo customTarget/vertexAIModel. Se você usar esse prefixo, use a seguinte sintaxe ao referenciar um parâmetro de implantação como uma variável de ambiente:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Em que VAR_NAME é o nome após a barra no nome do parâmetro de implantação. Por exemplo, se você definir um parâmetro de implantação chamado customTarget/vertexAIModel, faça referência a ele como CLOUD_DEPLOY_customTarget_vertexAIModel.

Parâmetros de implantação com hooks de implantação

É possível usar qualquer parâmetro de implantação como uma variável de ambiente em hooks de implantação.

Parâmetros de implantação com verificação de implantação

É possível usar qualquer parâmetro de implantação como uma variável de ambiente em verificação de implantação.

Conferir todos os parâmetros de uma versão

É possível conferir os parâmetros definidos para uma determinada versão. Eles são mostrados em uma tabela na página Detalhes da versão e na linha de comando (gcloud deploy releases describe).

  1. Na página principal do Cloud Deploy, clique no pipeline de entrega que inclui a versão que você quer conferir.

  2. Na página Detalhes da versão, selecione a guia Artefatos.

Todos os parâmetros de implantação definidos para essa versão são mostrados em uma tabela, com o nome e o valor da variável em uma coluna e o destino ou destinos afetados na outra coluna.

parâmetros de implantação e valores mostrados no console Google Cloud

A seguir