Neste documento, descrevemos como os destinos personalizados funcionam no Cloud Deploy.
O Cloud Deploy inclui suporte integrado para vários ambientes de execução como destinos. No entanto, a lista de tipos de segmentação compatíveis é finita. Com destinos personalizados, é possível implantar em outros sistemas além dos ambientes de execução compatíveis.
Um destino personalizado é um destino que representa um ambiente de saída arbitrário diferente de um ambiente de execução compatível com o Cloud Deploy.
Na página Criar um destino personalizado, descrevemos o processo de definição de um tipo de destino personalizado e sua implementação como um destino em um pipeline de entrega.
O que faz parte de uma segmentação personalizada?
Cada destino personalizado consiste nos seguintes componentes:
Ações personalizadas, definidas em
skaffold.yaml
Eles são semelhantes à definição de hooks de implantação. No arquivo
skaffold.yaml
, você definecustomActions
, em que cada ação personalizada identifica uma imagem de contêiner a ser usada e os comandos a serem executados nesse contêiner.Dessa forma, a meta personalizada é simplesmente uma ação ou um conjunto de ações definida de maneira personalizada.
Para qualquer tipo de destino personalizado, você configura uma ação de renderização e uma ação de implantação personalizadas. Essas ações consomem valores fornecidos pelo Cloud Deploy e precisam atender a um conjunto de saídas necessárias.
A ação de renderização personalizada é opcional, mas você precisa criar uma, a menos que o destino personalizado funcione corretamente se renderizado por
skaffold render
, que é o padrão para o Cloud Deploy.Uma definição de tipo de segmentação personalizada
O
CustomTargetType
é um recurso do Cloud Deploy que identifica as ações personalizadas (definidas separadamente em seuskaffold.yaml
) que visam esse tipo de uso para renderização de lançamento e atividades de implantação de lançamento.uma definição de destino.
A definição de um destino personalizado é a mesma de qualquer tipo de destino, exceto porque inclui a propriedade
customTarget
, cujo valor é o nome deCustomTargetType
.
Com esses componentes em vigor, é possível usar o destino como faria com qualquer destino, referenciando-o na progressão do pipeline de entrega e fazendo uso total dos recursos do Cloud Deploy, como promoção e aprovações e reversões.
Um exemplo
O guia de início rápido Definir e usar um tipo de destino personalizado cria um tipo de destino personalizado que inclui comandos simples para executar em uma imagem de contêiner: um comando para renderização e outro para implantação. Nesse caso, os comandos apenas adicionam texto aos arquivos de saída necessários para renderização e implantação.
Para mais exemplos, consulte Exemplos de segmentações personalizadas.
Entradas e saídas necessárias
Qualquer tipo de destino personalizado definido para o Cloud Deploy precisa atender aos requisitos de entrada e saída, tanto para renderização quanto para implantação. Nesta seção, listamos quais entradas e saídas são necessárias e como elas são fornecidas.
O Cloud Deploy fornece as entradas necessárias, para renderização e implantação, como variáveis de ambiente. As seções a seguir listam essas entradas, bem como as saídas que suas ações personalizadas de renderização e implantação precisam retornar.
Implantar parâmetros como variáveis de ambiente
Além das variáveis de ambiente listadas nesta seção, o Cloud Deploy pode transmitir para seus contêineres personalizados quaisquer parâmetros de implantação que você tenha definido.
Os parâmetros de implantação destinados como entradas para destinos personalizados precisam começar com
customTarget/
, por exemplo, customTarget/vertexAIModel
. Ao referenciar um
parâmetro de implantação como uma variável de ambiente, use a seguinte sintaxe:
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
.
Entradas para renderizar ações
Para ações de renderização personalizadas, o Cloud Deploy fornece as seguintes entradas necessárias, como variáveis de ambiente. Para lançamentos de várias fases (implantações canário), o Cloud Deploy fornece essas variáveis para cada fase.
CLOUD_DEPLOY_PROJECT
O projeto do Google Cloud em que o tipo de destino personalizado é criado.
CLOUD_DEPLOY_LOCATION
A região do Google Cloud para o tipo de destino personalizado.
CLOUD_DEPLOY_DELIVERY_PIPELINE
O nome do pipeline de entrega do Cloud Deploy que faz referência ao tipo de destino personalizado.
CLOUD_DEPLOY_RELEASE
O nome da versão para a qual a operação de renderização é invocada.
CLOUD_DEPLOY_TARGET
O nome do destino do Cloud Deploy que usa o tipo de destino personalizado.
CLOUD_DEPLOY_PHASE
A fase de lançamento à qual a renderização corresponde.
CLOUD_DEPLOY_REQUEST_TYPE
Para a ação de renderização personalizada, é sempre
RENDER
.CLOUD_DEPLOY_FEATURES
Uma lista separada por vírgulas de recursos do Cloud Deploy que o contêiner personalizado precisa aceitar. Essa variável é preenchida com base nos recursos configurados no pipeline de entrega.
Se a implementação não oferecer suporte aos recursos desta lista, recomendamos que ela falhe durante a renderização.
Para implantações padrão, esse valor fica vazio. Para implantações canário, o valor é
CANARY
. Se o valor fornecido pelo Cloud Deploy forCANARY
, a ação de renderização será invocada para cada fase no canário. A porcentagem de canários de cada fase é fornecida na variável de ambienteCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
A porcentagem de implantação associada a essa operação de renderização. Se a variável de ambiente
CLOUD_DEPLOY_FEATURES
for definida comoCANARY
, sua ação de renderização personalizada será chamada para cada fase, e essa variável será definida como a porcentagem de canários para cada fase. Para implantações padrão e para implantações canário que chegaram à fasestable
, isso é100
.CLOUD_DEPLOY_STORAGE_TYPE
O provedor de armazenamento. Sempre
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
O caminho do Cloud Storage para o arquivo do arquivo de renderização gravado quando a versão foi criada.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
O caminho do Cloud Storage em que o contêiner de renderização personalizado vai fazer upload dos artefatos que serão usados para implantação. Observe que a ação de renderização precisa fazer upload de um arquivo denominado
results.json
contendo os resultados dessa operação. Para saber mais, consulte Saídas da ação de renderização.
Saídas da ação de renderização
Sua ação de renderização personalizada precisa fornecer as informações descritas nesta
seção. As informações precisam ser incluídas no arquivo de resultados, chamado
results.json
, localizado no bucket do Cloud Storage fornecido pelo
Cloud Deploy.
Arquivo ou arquivos de configuração renderizados
Um arquivo
results.json
, contendo as seguintes informações:Uma indicação do estado de sucesso ou falha da ação personalizada.
Os valores válidos são:
SUCCEEDED
eFAILED
.(Opcional) Todas as mensagens de erro geradas pela ação personalizada.
O caminho do Cloud Storage para os arquivos de configuração renderizados.
O caminho de todos os arquivos de configuração renderizados é o URI completo. Você o preenche parcialmente usando o valor do
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornecido pelo Cloud Deploy.É preciso fornecer o arquivo de configuração renderizado, mesmo que ele esteja vazio. O conteúdo do arquivo pode ser qualquer coisa, em qualquer formato, desde que seja de consumo pela ação de implantação personalizada. Recomendamos que esse arquivo seja legível para que você e outros usuários da organização possam visualizá-lo no Inspetor de versões.
(Opcional) um mapa dos metadados que você quer incluir.
Seu destino personalizado cria esses metadados. Esses metadados são armazenados na versão, no campo
custom_metadata
.
Se você precisar examinar o arquivo results.json
, por exemplo, para depuração,
encontre o URI do Cloud Storage para ele nos registros do Cloud Build.
Exemplo de arquivo de resultados da renderização
Este é um exemplo de saída do arquivo results.json
de uma ação de renderização
personalizada:
{
"resultStatus": "SUCCEEDED",
"manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
"failureMessage": "",
"metadata": {
"key1": "val",
"key2": "val"
}
}
Entradas para implantar ações
Para ações de implantação personalizadas, o Cloud Deploy fornece as seguintes entradas necessárias, como variáveis de ambiente:
CLOUD_DEPLOY_PROJECT
O projeto do Google Cloud em que o destino personalizado é criado.
CLOUD_DEPLOY_LOCATION
A região do Google Cloud para o tipo de destino personalizado.
CLOUD_DEPLOY_DELIVERY_PIPELINE
O nome do pipeline de entrega do Cloud Deploy que faz referência ao destino que usa o tipo de destino personalizado.
CLOUD_DEPLOY_RELEASE
O nome da versão para a qual a operação de implantação é invocada.
CLOUD_DEPLOY_ROLLOUT
O nome do lançamento do Cloud Deploy a que esta implantação se destina.
CLOUD_DEPLOY_TARGET
O nome do destino do Cloud Deploy que usa o tipo de destino personalizado.
CLOUD_DEPLOY_PHASE
A fase de lançamento à qual a implantação corresponde.
CLOUD_DEPLOY_REQUEST_TYPE
Para a ação de implantação personalizada, é sempre
DEPLOY
.CLOUD_DEPLOY_FEATURES
Uma lista separada por vírgulas de recursos do Cloud Deploy que o contêiner personalizado precisa aceitar. Essa variável é preenchida com base nos recursos configurados no pipeline de entrega.
Se a implementação não oferecer suporte aos recursos desta lista, recomendamos que ela falhe durante a renderização.
Para implantações padrão, esse valor fica vazio. Para implantações canário, o valor é
CANARY
. Se o valor fornecido pelo Cloud Deploy forCANARY
, a ação de renderização será invocada para cada fase no canário. A porcentagem de canários de cada fase é fornecida na variável de ambienteCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
A porcentagem de implantação associada a essa operação de implantação. Se a variável de ambiente
CLOUD_DEPLOY_FEATURES
estiver definida comoCANARY
, sua ação de implantação personalizada será chamada para cada fase, e essa variável será definida como a porcentagem de canário em cada fase. A ação de implantação precisa ser executada para cada fase.CLOUD_DEPLOY_STORAGE_TYPE
O provedor de armazenamento. Sempre
GCS
.CLOUD_DEPLOY_INPUT_GCS_PATH
O caminho do Cloud Storage em que o renderizador personalizado gravou os arquivos de configuração renderizados.
CLOUD_DEPLOY_SKAFFOLD_GCS_PATH
O caminho do Cloud Storage para a configuração renderizada do Skaffold.
CLOUD_DEPLOY_MANIFEST_GCS_PATH
O caminho do Cloud Storage para o arquivo de manifesto renderizado.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
O caminho para o diretório do Cloud Storage em que o contêiner de implantação personalizado fará upload dos artefatos de implantação. Para mais informações, consulte Saídas da ação de implantação.
Saídas da ação de implantação
Sua ação de implantação personalizada precisa gravar um arquivo de saída results.json
. Esse arquivo
precisa estar localizado no bucket do Cloud Storage fornecido pelo
Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH
).
O arquivo precisa incluir o seguinte:
Uma indicação do estado de sucesso ou falha da ação de implantação personalizada.
Estes são os status válidos:
SUCCEEDED
FAILED
SKIPPED
para implantações canário, em que as fases canário são ignoradas para ir diretamente parastable
.
(Opcional) Uma lista de arquivos de artefato de implantação, na forma de caminhos do Cloud Storage
O caminho é o URI completo. Você o preenche parcialmente usando o valor do
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornecido pelo Cloud Deploy.Os arquivos listados aqui são preenchidos em recursos de execução de jobs como artefatos de implantação.
(opcional) uma mensagem de falha, se a ação de implantação personalizada não for bem-sucedida (retornando um estado
FAILED
).Essa mensagem é usada para preencher
failure_message
na execução do job para essa ação de implantação.(Opcional) Uma mensagem ignorada para fornecer mais informações se a ação retornar um status
SKIPPED
.(Opcional) um mapa dos metadados que você quer incluir.
Seu destino personalizado cria esses metadados. Esses metadados são armazenados na execução do job e no lançamento, no campo
custom_metadata
.
Se você precisar examinar o arquivo results.json
, por exemplo, para depuração,
encontre o URI do Cloud Storage para ele nos registros de renderização da versão
do Cloud Build.
Exemplo de arquivo de resultados da implantação
Este é um exemplo de saída do arquivo results.json
de uma ação de implantação
personalizada:
{
"resultStatus": "SUCCEEDED",
"artifactFiles": [
"gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
"gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
],
"failureMessage": "",
"skipMessage": "",
"metadata": {
"key1": "val",
"key2": "val"
}
}
Mais informações sobre ações personalizadas
Confira alguns pontos a serem considerados ao configurar e usar tipos de segmentação personalizados.
Executar as ações personalizadas
Suas ações personalizadas de renderização e implantação são executadas no ambiente de execução do Cloud Deploy. Não é possível configurar suas ações personalizadas para serem executadas em um cluster do Google Kubernetes Engine.
Como usar configurações remotas e reutilizáveis do Skaffold
Conforme descrito neste documento, você configura sua ação personalizada no
arquivo skaffold.yaml
fornecido na criação da versão. Também é possível armazenar as configurações do Skaffold em um repositório Git ou em um bucket do Cloud Storage e fazer referência a elas na definição de tipo de destino personalizado.
Isso permite usar ações personalizadas definidas e armazenadas em um único local compartilhado
em vez de incluir as ações personalizadas com o arquivo
skaffold.yaml
de cada versão.
Metas personalizadas e estratégias de implantação
Destinos personalizados são totalmente compatíveis com implantações padrão.
O Cloud Deploy é compatível com implantações canário, desde que o renderizador e o implantador personalizados sejam compatíveis com o recurso canário.
Use a configuração canário personalizada. Não há suporte para canários automatizados e personalizados.
Destinos personalizados e parâmetros de implantação
Use parâmetros de implantação com destinos personalizados. É possível defini-los no estágio do pipeline de entrega, no destino que usa um tipo de destino personalizado ou na versão.
Os parâmetros de implantação são transmitidos para os contêineres personalizados de renderização e implantação como variáveis de ambiente, além dos já fornecidos.
Exemplos de segmentações personalizadas
O repositório cloud-deploy-samples contém um conjunto de exemplos de implementações de destino personalizado. Os exemplos a seguir estão disponíveis:
GitOps
Vertex AI
Terraform
Infrastructure Manager
Helm
Cada amostra inclui um guia de início rápido.
Essas amostras não são produtos com suporte do Google Cloud e não estão cobertas por um contrato de suporte do Google Cloud. Para informar bugs ou solicitar recursos em um produto do Google Cloud, entre em contato com o suporte do Google Cloud.
A seguir
Agora que você conhece os destinos personalizados, saiba como configurá-los e usá-los.
Confira o guia de início rápido: definir e usar um tipo de destino personalizado.
Saiba mais sobre como configurar destinos do Cloud Deploy.
Saiba mais sobre os ambientes de execução do Cloud Deploy.