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 aos manifestos antes que esses manifestos sejam aplicados aos respectivos destinos. Essa substituição é feita depois que os manifestos forem renderizados. 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 do Cloud Deploy ou na configuração de destino, ou ao criar uma versão.

Este artigo descreve como fazer isso.

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

Um uso típico para isso seria a aplicação de valores diferentes a manifestos para destinos distintos em uma implantação paralela. Mas você pode 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

Nas etapas a seguir, descrevemos o processo geral para configurar os parâmetros de implantação e fornecer valores:

  1. Você configura a parametrização da implantação, conforme descrito aqui.

    Isso inclui o seguinte:

    • Adicione os marcadores ao manifesto.

    • Adicione valores para esses marcadores de posição.

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

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

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

    No entanto, é possível ter mais variáveis no manifesto para os 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.

    No momento da 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 da aplicação dos manifestos.

  3. Após a 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 ao 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 quaisquer parâmetros de implantação

Formas diferentes de transmitir valores

Você pode 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 um estágio na progressão do pipeline de entrega. O parâmetro é transmitido para o destino representado por essa fase. Se esse estágio 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 de todas as versões de um determinado pipeline em todos os destinos afetados. Os parâmetros definidos para um estágio identificam um rótulo, e o destino correspondente a essa fase precisa ter um rótulo correspondente.

  • Na definição do destino

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

  • Na linha de comando, quando você cria uma versão

    Inclua o parâmetro e o valor dele usando a sinalização --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 todos os destinos afetados.

Entenda a configuração deles em mais detalhes.

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 local, mas com valores diferentes, o comando gcloud deploy releases create falhará com um erro.

Qual é a diferença entre os recursos e os modelos de manifesto?

Conforme descrito neste artigo, os parâmetros de implantação são diferentes dos marcadores em um manifesto de modelo pela syntax. No entanto, se você está se perguntando por que precisa de parâmetros de implantação em vez de apenas usar as técnicas padrão para manifestos com modelos, a tabela abaixo mostra as diferentes finalidades:

Técnica Horário da substituição Válido para
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)
Dentro da meta Pós-renderização Todas as versões, destino específico

Este artigo é sobre somente parâmetros de implantação (na linha de comando, no pipeline e no destino), e não em manifestos com modelos.

Limitações

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

  • Um destino filho também pode herdar até 25 parâmetros do destino múltiplo pai, até um máximo de 100 parâmetros nos destinos, incluindo aqueles definidos no cenário do pipeline.

  • O nome da chave é limitado a um máximo de 512 caracteres e ao seguinte regex:

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

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

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

Configurar parâmetros de implantação

Nesta seção, descrevemos como configurar valores de parâmetro de implantação que serão aplicados ao manifesto do Kubernetes ou ao serviço do Cloud Run.

Além de configurar esses pares de chave-valor, você precisa adicionar os marcadores de posição ao manifesto, conforme descrito nesta seção.

Adicionar marcadores ao manifesto

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

Sintaxe

Esses marcadores usam a seguinte sintaxe:

[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 para essa propriedade na linha de comando, na configuração do pipeline ou do destino.

  • # 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 de posição a ser substituído. Ela precisa corresponder à chave de um par de chave-valor fornecida no pipeline de entrega ou na configuração de destino ou após a criação da versão.

Adicionar um parâmetro ao estágio do pipeline

É possível adicionar pares de chave-valor a uma fase no pipeline de entrega. Isso é útil em 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 no estágio do pipeline aplicável.

    O YAML a seguir é a configuração para um estágio de pipeline em que o 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"

    Nesta configuração do pipeline de entrega, a estrofe deployParameters inclui dois values, cada um com os seguintes itens:

    • O nome da variável, que é o mesmo nome da variável que você definiu no manifesto

    • Um valor para a variável

    • Um ou mais rótulos (opcional) para correspondência com 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 no cenário.

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

    O destino precisa corresponder a todos os rótulos definidos na estrofe values.

    Se você omitir matchTargetLabels, o values definido no pipeline será aplicado a todos os destinos filhos. No entanto, se você definir mais de um valor para o mesmo parâmetro, a versão 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 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 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}

    No manifesto, o parâmetro envvar1 é definido como um padrão de example1, e envvar2 é definido como um padrão de example2.

  2. Configure seus destinos para incluir deployParameters.

    Para cada parâmetro incluído, você identifica o seguinte:

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

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

    O YAML a seguir é a configuração para dois destinos. Cada destino inclui uma estrofe deployParameters que define um valor. Cada destino também inclui um rótulo para ser correspondido com os parâmetros de implantação configurados em um estágio 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 incluirem as chaves associadas.

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

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

  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
   annotations:
     commit: defaultShaValue # from-param ${git-sha}
   spec:
     containers:
     - name: nginx
       image: nginx:1.14.2

    Neste exemplo, o número de réplicas na implantação está definido como uma variável, $deploy_replicas.

    A sintaxe para essa variável é $ mais o nome da variável. Neste exemplo, é $deploy_replicas.

  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á 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 após a renderização do manifesto, o Cloud Deploy fornece os valores para os manifestos renderizados se eles incluirem as chaves associadas.

Acessar todos os parâmetros de uma versão

É possível visualizar os parâmetros que foram 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 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.

implantar parâmetros e valores mostrados no console do Google Cloud

A seguir