Neste documento, descrevemos como os destinos personalizados funcionam no Cloud Deploy.
O Cloud Deploy inclui suporte integrado para vários ambientes de execução ambientes como destinos. Mas a lista de tipos de destino compatíveis é finita. Com destinos personalizados, é possível implantar em outros fora 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 uma segmentação personalizada, o processo de definir um tipo de segmentação personalizada e implementá-lo 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 definido em
skaffold.yaml
O processo é parecido com a definição de hooks de implantação. Na
skaffold.yaml
, definacustomActions
, em que cada ação personalizada identifica uma imagem de contêiner para usar e os comandos a serem executados nesse contêiner.Dessa forma, o destino personalizado é simplesmente uma ação personalizada ou um conjunto de ações.
Para qualquer tipo de destino personalizado, você configura uma ação de renderização personalizada e uma uma ação de implantação do Google. Essas ações consomem valores fornecidos Cloud Deploy e precisa 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 sua o destino personalizado funcionará 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 emskaffold.yaml
) que segmentam desse tipo, use para atividades de renderização e implantação de lançamento de versão.uma definição de destino;
A definição da segmentação personalizada é a mesma de qualquer tipo de segmentação, exceto que inclui a propriedade
customTarget
, cujo valor é o nome doCustomTargetType
.
Com esses componentes prontos, você pode usar o alvo como faria com qualquer destino, referenciando-o da progressão do pipeline de entrega e fazendo uso pleno do recursos do Cloud Deploy, como promoção e aprovações, reversões.
Um exemplo
Guia de início rápido Definir e usar um tipo de segmentação personalizada cria um tipo de segmentação personalizada que inclui comandos simples para executar em um imagem de contêiner: um comando para renderização e outro para implantação. Os comandos, Nesse caso, basta adicionar texto aos arquivos de saída necessários para renderização e implantar.
Para mais exemplos, consulte Exemplos de segmentações personalizadas.
Entradas e saídas obrigatórias
Qualquer tipo de destino personalizado definido para o Cloud Deploy precisa atender requisitos de entrada e saída, tanto para renderização quanto para implantação. Esta seção lista quais entradas e saídas são necessárias e como são fornecidas.
O Cloud Deploy fornece as entradas necessárias, tanto para renderização implantar, 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 Implantar parâmetros que você definiu.
Os parâmetros de implantação destinados como entradas para destinos personalizados precisam começar com
customTarget/
, por exemplo, customTarget/vertexAIModel
. Ao mencionar uma
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 na
nome do parâmetro de implantação. Por exemplo, se você definir
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 oferece o seguinte: as 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 um tipo de segmentação personalizada.
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 destino personalizado não é válido.
CLOUD_DEPLOY_PHASE
A fase de lançamento ao 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 que o contêiner deve suportar. Essa variável é preenchida com base em recursos configurados no pipeline de entrega.
Caso sua implementação não ofereça suporte aos recursos desta lista, recomendamos que falhem durante a renderização.
Para implantações padrão, este campo está vazio. Para implantações canário, o valor é
CANARY
. Se o valor fornecido pelo Cloud Deploy éCANARY
, sua ação de renderização é invocadas em cada fase do canário. A porcentagem de canários para cada fase é fornecido 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 o A variável de ambiente
CLOUD_DEPLOY_FEATURES
está definida comoCANARY
, sua de renderização é chamada para cada fase, e essa variável é definida para o a porcentagem de canários em cada fase. Para implantações padrão e para implantações canário que atingiram a 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 de renderização gravado quando a versão foi criado.
CLOUD_DEPLOY_OUTPUT_GCS_PATH
O caminho do Cloud Storage em que o contêiner de renderização personalizado está você fará o upload dos artefatos que serão usados na implantação. Observe que o processo deve fazer upload de um arquivo chamado
results.json
contendo os resultados desta operação de renderização. Para mais informações, 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 neste
nesta seção. As informações devem ser incluídas no arquivo de resultados, chamado
results.json
, localizado no bucket do Cloud Storage fornecido pelo
Cloud Deploy.
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) As mensagens de erro geradas pela ação personalizada.
O caminho do Cloud Storage para o arquivo de configuração renderizado ou .
O caminho para todos os arquivos de configuração renderizados é o URI completo. Você preenchê-lo parcialmente usando o valor do
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornecido pelo Cloud Deploy.Forneça o arquivo de configuração renderizado, mesmo que ele esteja vazio. O o conteúdo do arquivo pode ser qualquer coisa, em qualquer formato, desde que seja por sua ação de implantação personalizada. Recomendamos que este arquivo seja humano legível, para que você e outros usuários em sua organização possam visualizar no Inspetor de versão.
(Opcional) Um mapa dos metadados que você quer incluir
Seu destino personalizado cria esses metadados. Esses metadados são armazenados lançamento, no campo
custom_metadata
.
Se você precisar examinar o arquivo results.json
, por exemplo, para depuração,
pode encontrar o URI do Cloud Storage nos registros do Cloud Build.
Exemplo de arquivo de resultados da renderização
Confira a seguir um exemplo de saída do arquivo results.json
de uma renderização personalizada
ação:
{
"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 os itens a seguir 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 que usa o tipo de segmentação personalizada.
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 essa implantação se destina.
CLOUD_DEPLOY_TARGET
O nome do destino do Cloud Deploy que usa o destino personalizado não é válido.
CLOUD_DEPLOY_PHASE
A fase de lançamento ao 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 que o contêiner deve suportar. Essa variável é preenchida com base em recursos configurados no pipeline de entrega.
Caso sua implementação não ofereça suporte aos recursos desta lista, recomendamos que falhem durante a renderização.
Para implantações padrão, este campo está vazio. Para implantações canário, o valor é
CANARY
. Se o valor fornecido pelo Cloud Deploy éCANARY
, sua ação de renderização é invocadas em cada fase do canário. A porcentagem de canários para cada fase é fornecido na variável de ambienteCLOUD_DEPLOY_PERCENTAGE_DEPLOY
.CLOUD_DEPLOY_PERCENTAGE_DEPLOY
A porcentagem de implantação associada a esta operação de implantação. Se o A variável de ambiente
CLOUD_DEPLOY_FEATURES
está definida comoCANARY
, sua de implantação é chamada para cada fase, e essa variável é definida para o a porcentagem de canários em cada fase. Sua ação de implantação precisa ser executada em 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 de configuração do Terraform.
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 a implantação personalizada é esperado que o contêiner faça 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
. Este arquivo
precisa estar 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.
Confira a seguir os status válidos:
SUCCEEDED
FAILED
SKIPPED
(para implantações canário em que as fases canário são ignoradas para ir direto aostable
.
(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 atributo
CLOUD_DEPLOY_OUTPUT_GCS_PATH
fornecido por Cloud Deploy.Os arquivos listados aqui são preenchidos recursos de execução do job como artefatos de implantação.
(opcional) uma mensagem de falha, se a ação de implantação personalizada não for concluída. (retornando um estado
FAILED
).Essa mensagem é usada para preencher o
failure_message
no execução do job para esta ação de implantação.(Opcional) Uma mensagem de pular, para fornecer informações adicionais se a ação retornar uma
SKIPPED
.(Opcional) Um mapa dos metadados que você quer incluir
Seu destino personalizado cria esses metadados. Esses metadados são armazenados 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,
o URI do Cloud Storage correspondente a ele no Cloud Build
liberar registros de renderização.
Exemplo de arquivo de resultados da implantação
Veja a seguir um exemplo de saída do arquivo results.json
de uma implantação personalizada
ação:
{
"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
Veja alguns pontos a serem considerados ao configurar e usar a segmentação personalizada tipos
Como executar as ações personalizadas
Suas ações personalizadas de renderização e implantação são executadas no Cloud Deploy ambiente de execução. Não é possível configurar suas ações personalizadas para execução 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. Mas você também pode armazenar
As configurações do Skaffold em um repositório Git ou em um bucket do Cloud Storage e
referencie-os na sua definição de tipo de segmentação personalizada.
Assim, é possível usar ações personalizadas definidas e armazenadas em um único local
local, em vez de incluir as ações personalizadas com os valores
skaffold.yaml
.
Destinos personalizados e estratégias de implantação
Os destinos personalizados são totalmente compatíveis com padrão.
O Cloud Deploy dá suporte a implantações canário, o renderizador e o implantador personalizados dão suporte ao recurso canário.
Use a configuração canário personalizada. Automatizado e personalizado canários não são aceitos.
Destinos personalizados e parâmetros de implantação
Você pode usar parâmetros de implantação com destinos personalizados. É possível defini-los no pipeline de entrega estágio, no destino que usa um tipo de segmentação personalizada versão.
Os parâmetros de implantação são passados para os contêineres personalizados de renderização e implantação, conforme variáveis de ambiente, além das aqueles que já foram 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 exemplo inclui um guia de início rápido.
Esses exemplos não são um produto compatível com o Google Cloud e não são cobertos por um contrato de suporte do Google Cloud. Para denunciar bugs ou solicitar recursos em um produto do Google Cloud, entre em contato com o suporte.
A seguir
Agora que você já conhece as segmentações personalizadas, descubra como configurá-las e usá-las.
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.