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 após os manifestos serem renderizados, como a etapa final na operação de renderização do Cloud Deploy. Os valores são fornecidos para todos os manifestos
identificados no seu arquivo skaffold.yaml
que contêm os marcadores
correspondentes.
Basta incluir marcadores de posição no manifesto e definir os valores deles 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 acontecer.
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 seu manifesto.
Como funciona
As etapas a seguir descrevem o processo geral para configurar parâmetros de implantação e fornecer valores:
Você configura a parametrização da 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, que são descritas aqui.
Quando você cria uma versão, seu 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 permanecerá inalterado. Essa renderização é feita pelo Skaffold (link em inglês).
No entanto, é possível ter outras variáveis no manifesto para valores em que não são aplicados no momento da renderização. Estes 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.
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 a 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.
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
Você pode 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 é passado para o destino representado por esse estágio. 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 para todas as versões em um determinado pipeline em todos os destinos afetados. Os parâmetros definidos para um cenário identificam um rótulo, e o destino correspondente para esse estágio precisa ter um rótulo correspondente.
-
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 comandogcloud 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.
Saiba mais sobre a configuração deles.
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.
Implantar parâmetros com destinos personalizados
Use qualquer parâmetro de implantação como variáveis de ambiente em destinos personalizados. Ao fazer isso, use a syntax especificada para destinos personalizados.
Qual é a diferença entre esse método e os modelos de manifesto?
Os parâmetros de implantação, conforme descrito neste artigo, são diferenciados 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 modelo, 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 |
Pipeline "On Delivery" | 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 de manifestos modelados.
Limitações
Para cada tipo de parâmetro, você pode criar no máximo 25 parâmetros.
Além disso, um destino filho pode herdar até 25 parâmetros do multidestino 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 63 caracteres e à seguinte expressão regular:
^[a-zA-Z0-9][-A-Za-z0-9_.]{0,61}[a-zA-Z0-9]$
Uma exceção é quando você usa um parâmetro de implantação como uma variável de ambiente em um destino personalizado, precisa 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 ver 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 pode ter no máximo 512 caracteres.
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, é preciso adicionar 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 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
Para versões que não usam o renderizador Helm com o 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 a propriedade na linha de comando, no pipeline ou na configuração de destino.
# from-param:
Usa um caractere de comentário para definir a diretiva
deploy-parameters
do Cloud Deploy, efrom-param:
informa ao Cloud Deploy que um marcadordeploy-parameters
segue.${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 após a criação da versão.
Sintaxe específica do Helm
Se você estiver usando o renderizador Helm com o Skaffold, use a seguinte sintaxe no seu modelo Helm para adicionar marcadores de posição:
[PROPERTY]: {{ .Values.VAR_NAME }}
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 em implantações paralelas, a fim de distinguir entre destinos filhos.
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
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 é vários destinos, que, neste 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"
Nesta configuração do pipeline de entrega, a estrofe
deployParameters
inclui doisvalues
, cada um com o seguinte:O nome da variável, que é o mesmo nome da variável que você definiu 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.
Se você incluiu
matchTargetLabels
, também precisa 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
, osvalues
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 destinos múltiplos.
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
é definido como um padrão deexample1
, eenvvar2
é definido como um padrão deexample2
.Configure os 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) definida 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
definindo um valor. Cada destino também inclui um rótulo, para 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 para a versão:
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 SHA de confirmação é definido como uma variável com o nome
${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 dessa variável é
$
mais o nome da variável entre chaves. Neste exemplo, é${git-sha}
.Ao criar uma versão, inclua a opção
--deploy-parameters
no comandogcloud 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 para os manifestos renderizados se eles incluirem as chaves associadas.
Conferir todos os parâmetros de uma versão
É possível visualizar os parâmetros definidos para uma determinada versão. Elas são
mostradas em uma tabela na página Detalhes da versão e na linha de comando
(gcloud deploy releases describe
).
Na página principal do Cloud Deploy, clique no pipeline de entrega que inclui a versão que você quer ver.
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 o destino ou os destinos afetados na outra coluna.
A seguir
Confira o guia de início rápido: usar parâmetros de implantação.
Saiba mais sobre o uso de implantações paralelas.