Transmitir parâmetros para a implantação

Com o Cloud Deploy, é possível transmitir parâmetros para sua versão, e esses valores são fornecidos ao manifesto ou manifestos antes que eles sejam aplicados aos respectivos destinos. Essa substituição é feita depois que os manifestos são rendered, 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 de posição correspondentes.

Basta incluir marcadores no manifesto e definir os valores deles no pipeline de entrega do Cloud Deploy, na configuração de destino ou ao criar um lançamento.

Neste artigo, descrevemos como fazer isso.

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

Um uso típico seria aplicar valores diferentes a manifestos para destinos diferentes em uma implantação paralela. Mas você pode usar parâmetros de implantação para qualquer coisa que exija substituição de par 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 de posição 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 um lançamento, o manifesto é rendered.

    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 vai 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 momento da renderização. Esses são os parâmetros de implantação descritos neste documento.

    Na criação do lançamento, todos os parâmetros de implantação são compilados em um dicionário, que é usado para substituir valores antes da aplicação dos manifestos.

  3. Depois da renderização, o Cloud Deploy substitui os valores pelos parâmetros de implantação.

    Esses são os valores que você configurou 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 momento da 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 eles de três maneiras:

  • Na definição do pipeline de entrega

    Você fornece o parâmetro e o valor dele na definição de uma etapa na progressão do pipeline de entrega. O parâmetro é transmitido para a meta representada por essa etapa. Se essa etapa se referir a um destino múltiplo, os valores definidos aqui serão usados para todos os destinos filhos.

    Esse método permite substituir um valor em todos os lançamentos de um pipeline específico, para todos os destinos afetados. Os parâmetros definidos para uma etapa identificam um rótulo, e a meta correspondente para essa etapa 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 todos os lançamentos.

  • Na linha de comando, ao criar um lançamento

    Inclua 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 do lançamento, aplicando esse valor aos manifestos de todas as metas afetadas.

A configuração para eles é explicada em mais detalhes aqui.

Posso usar mais de um desses métodos?

Sim, é possível incluir parâmetros de implantação na etapa 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 vai 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 de posição em um manifesto com modelo pela sintaxe. Mas 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 modelos, 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 Todos os lançamentos; destinos específicos (por rótulo)
Dentro da meta 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 modelos.

Limitações

  • Para cada tipo de parâmetro, é possível criar no máximo 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 na etapa 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ê usa 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 obrigatórias para ver 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 posição 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

Nesta seção, descrevemos 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, você precisa adicionar o marcador de posição ou os marcadores de posição ao manifesto, conforme descrito nesta seção.

Adicionar marcadores de posição ao manifesto

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

Sintaxe

Para versões que não usam o renderizador Helm com Skaffold, use a seguinte sintaxe para seus marcadores de posição:

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

Nesta linha...

  • PROPERTY:

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

  • DEFAULT_VALUE

    É um valor a ser usado se não houver valores fornecidos 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 de posição deploy-parameters vai aparecer.

  • ${VAR_NAME}

    É o marcador de posição a ser substituído. Ela precisa corresponder à chave de um par de chave-valor fornecido no pipeline de entrega ou na configuração de destino, ou na criação do lançamento.

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 na etapa de destino ou 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 Helm que aceita valores de configuração e quiser definir esses valores usando parâmetros de implantação, os parâmetros de implantação precisarão 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 argumentos --set no momento da renderização, sem necessidade de modificar o skaffold.yaml.

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

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

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

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 uma etapa na progressão do pipeline de entrega. Isso é útil para implantações paralelas, para distinguir entre destinos filhos.

  1. Adicione os marcadores de posição 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 na etapa aplicável do pipeline.

    O YAML a seguir é a configuração de uma etapa de pipeline cujo destino é um destino múltiplo, que neste 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"

    Nesta configuração de pipeline de entrega, a estrofe 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 aos rótulos específicos do destino

      Se você não especificar um rótulo em uma estrofe matchTargetLabels, esse valor será usado para todos os destinos na etapa.

  3. Se você incluiu matchTargetLabels, também precisa incluir rótulos nos destinos para que eles correspondam. Assim, você identifica qual valor atribuir a qual segmentação por crianças.

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

    Se você omitir matchTargetLabels, o values definido no pipeline será aplicado a todos os destinos filhos. Mas se você definir mais de um valor para o mesmo parâmetro, o lançamento vai 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 uma segmentação. Se você estiver usando parâmetros de implantação para distinguir entre vários destinos filhos, configure-os nesses destinos filhos, e não no destino múltiplo.

  1. Configure o manifesto do Kubernetes ou a definição do 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 está definido como o padrão example1, e envvar2 está definido como o padrão example2.

  2. Configure suas metas para incluir deployParameters.

    Para cada parâmetro incluído, 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 padrão definido no manifesto será usado.

    O YAML a seguir é a configuração de duas metas. Cada meta inclui uma estrofe deployParameters que define um valor. Cada destino também inclui um rótulo, que será correspondido aos parâmetros de implantação configurados em uma etapa do 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 do lançamento

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

  1. Configure o manifesto do Kubernetes ou a definição de serviço do Cloud Run usando um parâmetro em vez 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 do commit é definido como uma variável chamada ${git-sha}. Um valor para isso é transmitido na criação do lançamento usando a opção --deploy-parameters=, como visto na próxima etapa.

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

  2. Ao criar um lançamento, 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 de posição que você adicionou ao manifesto.

    O comando será parecido com 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 depois da renderização do manifesto, o Cloud Deploy fornece os valores aos manifestos renderizados se eles incluírem as chaves associadas.

Implantar parâmetros 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 metas personalizadas 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.

Implantar parâmetros 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.

Implantar parâmetros com verificação de implantação

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

Conferir todos os parâmetros de uma versão

É possível conferir os parâmetros definidos para uma versão específica. 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 ver.

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

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

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

A seguir