Sobre as segmentações personalizadas

Este documento descreve 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 fazer a implantação em outros sistemas além dos tempos 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.

A página Criar uma meta personalizada descreve o processo de definição de um tipo de meta personalizada e implementação dela como uma meta em um pipeline de entrega.

O que é incluído em um destino personalizado?

Cada segmentação personalizada consiste nos seguintes componentes:

  • Tarefas, que definem como renderizar e implantar para seu tipo de destino personalizado

    Suas implementações de renderização e implantação personalizadas consomem valores fornecidos pelo Cloud Deploy e precisam atender a um conjunto de saídas obrigatórias.

    A renderização personalizada é opcional, mas você precisa criar uma, a menos que seu destino personalizado funcione corretamente se for renderizado com os renderizadores integrados do Cloud Deploy.

  • Uma definição de tipo de segmentação personalizada

    O CustomTargetType é um recurso do Cloud Deploy que identifica as tarefas que os destinos desse tipo usam para renderização de versões e implantação de lançamento de atividades.

  • Uma definição de destino

    A definição de destino para um destino personalizado é a mesma de qualquer tipo de destino, exceto que ela inclui a propriedade customTarget, cujo valor é o nome do CustomTargetType.

Com esses componentes no lugar, você pode usar o destino como qualquer outro, referenciando-o na progressão do pipeline de entrega e aproveitando ao máximo os 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 para execução em uma imagem de contêiner: um comando para renderização e outro para implantação. Neste 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 metas personalizadas.

Entradas e saídas obrigató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. Esta seção lista quais entradas e saídas são necessárias e como elas são fornecidas.

O Cloud Deploy fornece as entradas necessárias, tanto para renderização quanto para implantação, como variáveis de ambiente. As seções a seguir listam essas entradas, bem como as saídas que sua renderização e implantação personalizadas 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 aos seus contêineres personalizados todos os parâmetros de implantação definidos.

Saiba mais.

Entradas para renderizações personalizadas

Para renderizações personalizadas, o Cloud Deploy fornece as seguintes entradas como variáveis de ambiente. Para implantações multifásicas (implantações canário), o Cloud Deploy fornece essas variáveis para cada fase.

  • CLOUD_DEPLOY_PROJECT

    O número do projeto Google Cloud em que a meta personalizada é criada.

  • CLOUD_DEPLOY_PROJECT_ID

    O ID do projeto Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    A região Google Cloud para o tipo de segmentação personalizada.

  • 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 a que a renderização corresponde.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para a renderização personalizada, esse valor é sempre RENDER.

  • CLOUD_DEPLOY_FEATURES

    Uma lista separada por vírgulas de recursos do Cloud Deploy que o contêiner personalizado precisa oferecer suporte. Essa variável é preenchida com base nos recursos configurados no pipeline de entrega.

    Se a implementação não for compatível com os recursos desta lista, recomendamos que ela falhe durante a renderização.

    Para implantações padrão, esse campo fica vazio. Para implantações canário, o valor é CANARY. Se o valor fornecido pelo Cloud Deploy for CANARY, a renderização será invocada para cada fase no lançamento canário. A porcentagem de canário para cada fase é fornecida na variável de ambiente CLOUD_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 estiver definida como CANARY, a renderização personalizada será chamada para cada fase, e essa variável será definida como a porcentagem de canário para cada fase. Para implantações padrão e para implantações canário que atingiram a fase stable, esse valor é 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 criada.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    O caminho do Cloud Storage em que o contêiner de renderização personalizada deve fazer upload de artefatos para serem usados na implantação. A renderização precisa fazer upload de um arquivo chamado results.json com os resultados dessa operação. Para mais informações, consulte Saídas da renderização personalizada.

Saídas da renderização personalizada

A 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 (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

  • Arquivo ou arquivos de configuração renderizados

  • Um arquivo results.json com as seguintes informações:

    • Uma indicação do estado de sucesso ou falha da renderização personalizada.

      Os valores válidos são: SUCCEEDED e FAILED.

    • (Opcional) todas as mensagens de erro geradas pela renderização personalizada.

    • O caminho do Cloud Storage para o arquivo ou arquivos de configuração renderizados.

      O caminho para todos os arquivos de configuração renderizados é o URI completo. Você preenche parcialmente usando o valor do CLOUD_DEPLOY_OUTPUT_GCS_PATH fornecido pelo Cloud Deploy.

      Você precisa 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 consumível pela sua implantação personalizada. Recomendamos que esse arquivo seja legível para humanos, para que você e outros usuários da sua organização possam visualizá-lo no Release Inspector.

    • (Opcional) um mapa de todos os 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 nos registros do Cloud Build.

Exemplo de arquivo de resultados de renderização

Confira a seguir um exemplo de saída de arquivo results.json de uma 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 implantações personalizadas

Para implantações personalizadas, o Cloud Deploy fornece as seguintes entradas como variáveis de ambiente:

  • CLOUD_DEPLOY_PROJECT

    O número do projeto Google Cloud em que a meta personalizada é criada.

  • CLOUD_DEPLOY_PROJECT_ID

    O ID do projeto Google Cloud .

  • CLOUD_DEPLOY_LOCATION

    A região Google Cloud para o tipo de segmentação personalizada.

  • 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 a que a implantação corresponde.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para a implantação personalizada, esse valor é sempre DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Uma lista separada por vírgulas de recursos do Cloud Deploy que o contêiner personalizado precisa oferecer suporte. Essa variável é preenchida com base nos recursos configurados no pipeline de entrega.

    Se a implementação não for compatível com os recursos desta lista, recomendamos que ela falhe durante a renderização.

    Para implantações padrão, esse campo fica vazio. Para implantações canário, o valor é CANARY. Se o valor fornecido pelo Cloud Deploy for CANARY, a implantação será invocada para cada fase no canary. A porcentagem de canário para cada fase é fornecida na variável de ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    A porcentagem de implantação associada a essa operação. Se a variável de ambiente CLOUD_DEPLOY_FEATURES estiver definida como CANARY, a implantação personalizada será chamada para cada fase, e essa variável será definida como a porcentagem de canário para cada fase. A 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 arquivos de configuração renderizados.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    O caminho do Cloud Storage para a configuração renderizada do Skaffold. Se você forneceu uma configuração do Skaffold com sua versão.

  • 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 personalizada deve fazer upload dos artefatos de implantação. Para mais informações, consulte Saídas de implantação personalizada.

Saídas da implantação personalizada

A 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 implantação personalizada.

    Os seguintes status são válidos:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Isso é para implantações canário em que as fases canário são ignoradas para ir direto para stable.

  • (Opcional) Uma lista de arquivos de artefato de implantação, na forma de caminhos do Cloud Storage

    O caminho é o URI completo. Ele é preenchido 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 implantação personalizada não for bem-sucedida (retornando um estado FAILED)

    Essa mensagem é usada para preencher o failure_message na execução do job dessa implantação.

  • (Opcional) uma mensagem de rejeição para fornecer mais informações se a implantação retornar um status SKIPPED.

  • (Opcional) um mapa de todos os 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 nos registros do Cloud Build.

Exemplo de arquivo de resultados da implantação

Confira a seguir um exemplo de saída de arquivo results.json de uma 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 metas personalizadas

Confira algumas coisas a serem consideradas ao configurar e usar tipos de segmentação personalizada.

Execução das tarefas

Suas tarefas personalizadas de renderização e implantação são executadas no ambiente de execução do Cloud Deploy. Não é possível configurar suas tarefas para serem executadas em um cluster do Google Kubernetes Engine.

Metas personalizadas e estratégias de implantação

Os destinos personalizados são totalmente compatíveis com implantações padrão.

O Cloud Deploy oferece suporte a implantações canário desde que o renderizador e o implantador personalizados sejam compatíveis com o recurso canário.

Você precisa usar uma configuração canário personalizada. Os canários automáticos e personalizados não são compatíveis com destinos personalizados.

Segmentações personalizadas e parâmetros de implantação

É possível usar parâmetros de implantação com destinos personalizados. É possível definir essas opções no estágio do pipeline de entrega, na meta que usa um tipo de meta personalizada ou na versão.

Os parâmetros de implantação são transmitidos aos seus contêineres personalizados de renderização e implantação como variáveis de ambiente, além daqueles já fornecidos.

Exemplos de segmentações personalizadas

O repositório cloud-deploy-samples contém um conjunto de exemplos de implementações de destino personalizadas. As seguintes amostras estão disponíveis:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Helm

Cada amostra inclui um início rápido.

Essas amostras não são um produto Google Cloud com suporte e não estão cobertas por um contrato de suporte Google Cloud . Para informar bugs ou solicitar recursos em um produto Google Cloud , entre em contato com o suporte Google Cloud.

A seguir