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 eles sejam aplicados aos respectivos destinos. Essa substituição é feita depois que os manifestos são renderizados, como 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.

Tudo o que você precisa fazer é incluir marcadores de posição no manifesto e definir os valores para eles no pipeline de entrega do Cloud Deploy, na configuração de destino ou ao criar uma versão.

Este artigo descreve como fazer isso acontecer.

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

Um uso típico para isso é na aplicação de valores distintos a manifestos para diferentes destinos em uma implantação paralela. No entanto, você pode usar parâmetros de implantação para qualquer coisa que exija a substituição de par de chave-valor pós-renderização no seu 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.

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

      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 às variáveis de modelo. Se você começar com um manifesto bruto, ele vai continuar 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. Estes 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 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á aplicava valores aos modelos de manifesto, substituindo alguns valores e adicionando rótulos específicos do Cloud Deploy. Mas 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

Maneiras diferentes 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 progresso do pipeline de entrega. O parâmetro é passado para o destino representado por esse estágio. Se esse cenário referenciar 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 cenário identificam um rótulo, e o destino correspondente a esse estágio 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 do destino em todas as versões.

  • Na linha de comando, ao criar 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 de criação da versão, aplicando esse valor aos manifestos de todos os destinos afetados.

A configuração desses recursos é 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 local, mas com valores diferentes, o comando gcloud deploy releases create falhará com um erro.

Implantar parâmetros com destinos personalizados

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

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

Os parâmetros de implantação, conforme descrito neste artigo, se distinguem dos marcadores em um manifesto com modelo pela syntax. No entanto, se você está se perguntando por que precisa de parâmetros de implantação em vez de usar as técnicas padrão para manifestos com modelo, a tabela a seguir 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 documento trata apenas de parâmetros de implantação (na linha de comando, pipeline e destino), e não manifestos com modelos.

Limitações

  • É possível criar até 25 parâmetros para cada tipo de parâmetro.

  • Um destino filho também pode herdar até 25 parâmetros da multisegmentação pai, até um máximo de 100 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 a seguinte expressão regular:

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

    Uma exceção é que, ao usar um parâmetro de implantação como uma variável de ambiente em um destino personalizado, você precisa 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 conferir a sintaxe compatível.

  • O prefixo CLOUD_DEPLOY_ está 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 ter no máximo 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

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, é necessário adicionar os marcadores ao manifesto, conforme descrito nesta seção.

Adicionar marcadores de posição 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ê quiser substituir após a renderização.

Sintaxe

Para versões que não usam o renderizador Helm com o Skaffold, use a seguinte sintaxe para os 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 de 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.

  • # from-param:

    Usa um caractere de comentário para desativar a diretiva deploy-parameters do Cloud Deploy, e from-param: informa ao Cloud Deploy que um marcador de posição 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.

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 precisarão ter nomes correspondentes aos valores de configuração do Helm que você quer definir. Todos os parâmetros de implantação são transmitidos para o Helm como argumentos --set no momento da renderização, sem necessidade de modificação do skaffold.yaml.

Por exemplo, se o skaffold.yaml estiver instalando um gráfico do Helm que use 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 que você quer 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 esses modelos, poderá usar a sintaxe de variável padrão do Helm de {{ .Values.VAR_NAME }} nos seus modelos.

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 no estágio do pipeline aplicável.

    O YAML a seguir é a configuração de um estágio de pipeline que tem vários destinos que, nesse caso, têm 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 do pipeline de entrega, a estrofe deployParameters inclui dois values, cada um com o seguinte:

    • O nome da variável, que é igual ao 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 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 que eles sejam correspondentes. 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, 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 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 nos de vários destinos.

  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 está definido como um padrão de example1, e envvar2 está 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 é igual à chave (variável) definida no manifesto.

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

    O YAML a seguir é a configuração de dois destinos. Cada destino inclui uma estrofe de deployParameters que define um valor. Cada destino também inclui um rótulo, que deve ser combinado com os 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 incluirem 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 visto na próxima etapa.

    A sintaxe desta 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 pega 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 para os manifestos renderizados se eles incluirem as chaves associadas.

Ver todos os parâmetros de uma versão

É possível visualizar os parâmetros que foram definidos para uma determinada versão. Elas são exibidas 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 que foram 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 coluna.

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

A seguir