Transmita parâmetros para a sua implementação

Com o Cloud Deploy, pode transmitir parâmetros para a sua versão, e esses valores são fornecidos ao manifesto ou aos manifestos antes de serem aplicados aos respetivos destinos. Esta substituição é feita depois de os manifestos serem rendered, como o passo final na operação de renderização do Cloud Deploy. Os valores são fornecidos a todos os manifestos identificados no seu ficheiro skaffold.yaml que contenham os marcadores de posição correspondentes.

Só tem de incluir marcadores de posição no manifesto e definir os valores desses marcadores de posição no pipeline de implementação do Cloud Deploy ou na configuração de destino, ou quando cria uma versão.

Este artigo descreve como o fazer.

Por que motivo deve usar parâmetros de implementação?

Uma utilização típica desta funcionalidade seria aplicar valores diferentes a manifestos para diferentes alvos numa implementação paralela. No entanto, pode usar parâmetros de implementação para tudo o que exija a substituição de pares de chave-valor pós-renderização no manifesto.

Como funciona

Os passos seguintes descrevem o processo geral de configuração dos parâmetros de implementação e fornecimento de valores:

  1. Configura a parametrização da implementação, conforme descrito aqui.

    Isto inclui o seguinte:

    • Adicione os marcadores de posição ao manifesto, incluindo um valor predefinido para cada um.

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

      Existem três formas de o fazer, descritas aqui.

  2. Quando cria um lançamento, o manifesto é rendered.

    Se começar com um manifesto baseado em modelos, os valores são aplicados agora às variáveis do modelo. Se começar com um manifesto não processado, este permanece inalterado. Esta renderização é feita pelo Skaffold.

    No entanto, pode ter variáveis adicionais no manifesto para as quais os valores não são aplicados no momento da renderização. Estes são os parâmetros de implementação descritos neste documento.

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

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

    Estes são os valores que configurou no primeiro passo.

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

  4. O manifesto é aplicado ao tempo de execução de destino para implementar a sua aplicação.

    Isto inclui os valores substituídos no momento da renderização e os valores de quaisquer parâmetros de implementação

Diferentes formas de transmitir valores

Pode fornecer parâmetros e valores para esses parâmetros de três formas:

  • Na definição do pipeline de entrega

    Fornece o parâmetro e o respetivo valor na definição de uma fase na progressão do pipeline de entrega. O parâmetro é transmitido ao destino representado por essa fase. Se essa fase fizer referência a uma segmentação múltipla, os valores definidos aqui são usados para todos os alvos secundários.

    Este método permite-lhe substituir um valor para todos os lançamentos num determinado pipeline, para todos os destinos afetados. Os parâmetros definidos para uma fase identificam uma etiqueta e o destino correspondente para essa fase tem de ter uma etiqueta correspondente.

  • Na definição do alvo

    Configura o parâmetro e o respetivo valor na definição do alvo. Este método permite-lhe substituir um valor para esse alvo em todos os lançamentos.

  • Na linha de comandos, quando cria um lançamento

    Inclui o parâmetro e o respetivo valor através da flag --deploy-parameters no comando gcloud deploy releases create.

    Este método permite-lhe substituir um valor no momento da criação do lançamento, aplicando esse valor aos manifestos de todos os alvos afetados.

A configuração destas opções é explicada mais detalhadamente aqui.

Posso usar mais do que um destes métodos?

Sim, pode incluir parâmetros de implementação na fase do pipeline, na configuração de destino e na linha de comandos. O resultado é que todos os parâmetros são aceites 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 falha com um erro.

Em que medida é que isto é diferente dos modelos de manifesto

Os parâmetros de implementação, conforme descrito neste artigo, distinguem-se dos marcadores de posição num manifesto baseado em modelos pela sintaxe. No entanto, se se questionar por que motivo precisa de implementar parâmetros em vez de usar apenas as técnicas padrão para manifestos baseados em modelos, a tabela seguinte mostra os diferentes objetivos:

Técnica Tempo de substituição Aplica-se a
Modelo de manifesto Fase de renderização Lançamento específico; alvo específico
Na linha de comandos Pós-renderização Lançamento específico; todos os alvos
No pipeline de fornecimento Pós-renderização Todos os lançamentos; alvos específicos (por editora)
Dentro do objetivo Pós-renderização Todos os lançamentos; alvo específico

Este documento aborda apenas os parâmetros de implementação (na linha de comandos, no pipeline e no destino) e não os manifestos baseados em modelos.

Limitações

  • Para cada tipo de parâmetro, pode criar um máximo de 50 parâmetros.

  • Uma segmentação secundária pode, adicionalmente, herdar até 50 parâmetros da respetiva segmentação múltipla principal, até um máximo de 200 parâmetros nas segmentações, incluindo os definidos na fase do pipeline.

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

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

    Uma exceção a isto ocorre quando usa um parâmetro de implementação como uma variável de ambiente num alvo personalizado. Nesse caso, tem de usar uma barra entre a palavra-chave customTarget e o nome da variável (customTarget/VAR_NAME). Consulte as entradas e saídas necessárias para ver a sintaxe suportada.

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

  • Não pode ter duas chaves com o mesmo nome aplicadas ao mesmo destino.

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

  • Não é possível usar marcadores de posição de parâmetros de implementação para valores de configuração do Helm, mas têm de ser transmitidos por convenção.

Configure os parâmetros de implementação

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

Além de configurar esses pares de chave-valor, tem de adicionar o marcador de posição ou os marcadores de posição ao seu manifesto, conforme descrito nesta secção.

Adicione marcadores de posição ao manifesto

No manifesto do Kubernetes (para o GKE) ou no YAML do serviço (para o Cloud Run), adiciona marcadores de posição para quaisquer valores que queira substituir após a renderização.

Sintaxe

Para lançamentos 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 está no manifesto do Kubernetes ou no YAML do serviço do Cloud Run.

  • DEFAULT_VALUE

    É um valor a usar se não forem fornecidos valores para esta propriedade na linha de comandos ou na configuração do pipeline ou do destino. O valor predefinido é obrigatório, mas pode ser uma string vazia ("").

  • # from-param:

    Usa um caráter de comentário para separar a diretiva do Cloud Deploy deploy-parameters e from-param: indica ao Cloud Deploy que se segue um marcador de posição deploy-parameters.

  • ${VAR_NAME}

    É o marcador de posição a substituir. Isto tem de corresponder à chave de um par chave-valor fornecido no pipeline de fornecimento ou na configuração de destino, ou aquando da criação da versão.

Também pode usar vários parâmetros numa única linha e usar os parâmetros 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}

Estes parâmetros podem ser provenientes de várias origens. No exemplo anterior, ${artifactRegion} seria provavelmente definido na fase de destino ou pipeline de fornecimento, enquanto ${imageSha} viria da linha de comandos no momento da criação do lançamento.

Parâmetros para valores do gráfico Helm

Se estiver a renderizar um gráfico Helm que aceite valores de configuração e quiser definir esses valores através de parâmetros de implementação, os parâmetros de implementação têm de ter nomes que correspondam aos valores de configuração do Helm que quer definir. Todos os parâmetros de implementação são transmitidos ao Helm como argumentos --set no momento da renderização, sem necessidade de modificar o seu skaffold.yaml.

Por exemplo, se o seu skaffold.yaml estiver a instalar um gráfico Helm que recebe um parâmetro de configuração de webserver.port para especificar em que porta o servidor Web vai ser iniciado e quiser definir este parâmetro dinamicamente a partir de um parâmetro de implementação, tem de criar um parâmetro de implementação com o nome webserver.port com o valor pretendido para a porta do servidor Web.

Por conseguinte, se não estiver apenas a fazer referência a modelos Helm em skaffold.yaml, mas também a criá-los, pode usar a sintaxe de variáveis Helm padrão de {{ .Values.VAR_NAME }} nos seus modelos Helm.

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

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

Adicione um parâmetro à fase do pipeline

Pode adicionar pares de chave-valor a uma fase na progressão do pipeline de publicação. Isto é útil para implementações paralelas, para distinguir entre destinos secundários.

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

    Segue-se 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 fornecimento para incluir deployParameters para a fase do pipeline aplicável.

    O YAML seguinte é a configuração de uma fase do pipeline cujo destino é um destino múltiplo, que, neste caso, tem dois destinos secundários:

    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 da pipeline de entrega, a secção deployParameters inclui dois values, cada um dos quais tem o seguinte:

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

    • Um valor para essa variável

    • Uma ou mais etiquetas (opcional) para corresponder a etiquetas específicas do destino

      Se não especificar uma etiqueta, numa secção matchTargetLabels, esse valor é usado para todos os alvos na fase.

  3. Se incluiu matchTargetLabels , também tem de incluir etiquetas nos alvos para que correspondam. Desta forma, identifica que valor atribuir a que alvo secundário.

    O destino tem de corresponder a todas as etiquetas definidas na secção values.

    Se omitir matchTargetLabels, o values que definir no pipeline é aplicado a todos os alvos secundários. No entanto, se definir mais do que um valor para o mesmo parâmetro, a versão falha.

Após a renderização de cada manifesto, o Cloud Deploy adiciona o valor de cada variável ao manifesto renderizado.

Adicione um parâmetro à configuração do alvo

Pode adicionar pares de chave-valor a um alvo. Se estiver a usar parâmetros de implementação para distinguir entre várias segmentações secundárias, configure-os nessas segmentações secundárias e não na segmentação múltipla.

  1. Configure o manifesto do Kubernetes ou a definição do serviço do Cloud Run com um parâmetro em vez do valor que quer definir no momento da implementação.

    Segue-se 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}

    Neste manifesto, o parâmetro envvar1 está predefinido como example1 e envvar2 está predefinido como example2.

  2. Configure as suas segmentações para incluir deployParameters.

    Para cada parâmetro que incluir, identifica o seguinte:

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

    • Um valor para essa chave. Se não fornecer um valor, é usado o valor predefinido definido no manifesto.

    O YAML seguinte é a configuração de dois destinos. Cada alvo inclui uma secção deployParameters que define um valor. Cada destino também inclui uma etiqueta, a ser associada aos parâmetros de implementação configurados numa fase 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 de os manifestos serem renderizados, o Cloud Deploy adiciona estes valores aos manifestos renderizados se incluírem as chaves associadas.

Transmita um parâmetro na criação do lançamento

Siga estes passos para transmitir parâmetros e valores para o lançamento:

  1. Configure o manifesto do Kubernetes ou a definição do serviço do Cloud Run com um parâmetro em vez do valor que quer definir no momento da implementação.

    Segue-se 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 denominada ${git-sha}. É transmitido um valor para esta opção no momento da criação do lançamento, através da opção --deploy-parameters=, como se vê no passo seguinte.

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

  2. Quando criar um lançamento, inclua a opção --deploy-parameters no comando gcloud deploy releases create.

    --deploy-parameters usa uma lista de pares de chave-valor separados por vírgulas, em que a chave é o marcador de posição que adicionou ao manifesto.

    O comando vai ter um aspeto semelhante ao seguinte:

    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 incluírem as chaves associadas.

Implemente parâmetros com segmentações personalizadas

Pode usar qualquer parâmetro de implementação como uma variável de ambiente em alvos personalizados. Ao fazê-lo, use a sintaxe especificada para segmentações personalizadas.

Os parâmetros implementados destinados a entradas para segmentações personalizadas podem começar com customTarget/, por exemplo, customTarget/vertexAIModel. Se usar este prefixo, use a seguinte sintaxe quando fizer referência a um parâmetro de implementação como uma variável de ambiente:

CLOUD_DEPLOY_customTarget_[VAR_NAME]

Em que VAR_NAME é o nome que se segue à barra no nome do parâmetro de implementação. Por exemplo, se definir um parâmetro de implementação denominado customTarget/vertexAIModel, faça referência ao mesmo como CLOUD_DEPLOY_customTarget_vertexAIModel.

Implemente parâmetros com hooks de implementação

Pode usar qualquer parâmetro de implementação como uma variável de ambiente nos hooks de implementação.

Implemente parâmetros com a validação da implementação

Pode usar qualquer parâmetro de implementação como uma variável de ambiente na validação da implementação.

Veja todos os parâmetros de um lançamento

Pode ver os parâmetros definidos para um determinado lançamento. São apresentados numa tabela na página Detalhes do lançamento e na linha de comandos (gcloud deploy releases describe).

  1. Na página principal do Cloud Deploy, clique no pipeline de implementação que inclui o lançamento que quer ver.

  2. Na página Detalhes do lançamento, selecione o separador Artefactos.

Todos os parâmetros de implementação definidos para esta versão são apresentados numa tabela, com o nome e o valor da variável numa coluna e o alvo ou alvos afetados na outra coluna.

Implemente parâmetros e valores apresentados na consola Google Cloud

O que se segue?