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 ambientes como destinos. Mas a lista de tipos de destino aceitos é finita. Com destinos personalizados, é possível implantar em outros fora dos ambientes de execução compatíveis.

Um destino personalizado representa um ambiente de saída arbitrário, diferente do ambiente de execução compatível com o Cloud Deploy.

A página Criar um destino personalizado descreve o processo de definição de um tipo de destino personalizado e sua implementação como 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

    Elas são semelhantes à forma como você define deploy hooks. No arquivo skaffold.yaml, você define customActions, 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 segmentação personalizada é simplesmente uma ação personalizada ou um conjunto de ações.

    Para qualquer tipo de segmentação personalizada, você configura uma ação de renderização personalizada e uma ação de implantação personalizada. 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 o destino personalizado funcione corretamente se renderizado por skaffold render, que é o padrão do 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 skaffold.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 de destino para um destino personalizado é igual a qualquer outro tipo de destino, exceto por incluir a propriedade customTarget, cujo valor é o nome do CustomTargetType.

Com esses componentes em vigor, você pode usar o destino como faria com qualquer outro, fazendo referência a ele na progressão do pipeline de entrega e usando todos os recursos do Cloud Deploy, como promoção e aprovações e reversão.

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, neste caso, 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 obrigatórias

Qualquer tipo de destino personalizado definido para o Cloud Deploy precisa atender aos requisitos de entrada e saída, para renderização e 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 as 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.

Saiba mais.

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 em 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 tipo de destino personalizado.

  • CLOUD_DEPLOY_PHASE

    A fase de lançamento a que o render 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 nos 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, ele fica 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á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 o A variável de ambiente CLOUD_DEPLOY_FEATURES está definida como CANARY, sua de renderização é chamada para cada fase, e essa variável é definida como o a porcentagem de canários em cada fase. Para implantações padrão e implantações canário que alcançaram 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 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 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 e FAILED.

    • (Opcional) Todas as mensagens de erro geradas pela ação personalizada.

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

      O caminho de 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 conteúdo do arquivo pode ser qualquer coisa, em qualquer formato, desde que seja consumível pela sua ação de implantação personalizada. Recomendamos que esse arquivo seja legível por humanos, para que você e outros usuários da sua organização possam acessá-lo no Release Inspector.

    • (Opcional) Um mapa dos metadados que você quer incluir

      O 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, 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 de 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 o seguinte 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 para o qual 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 o deploy 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 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, este campo está vazio. Para implantações canário, o valor é CANARY. Se o valor fornecido pelo Cloud Deploy for CANARY, a ação de renderização será invocada para cada fase no canário. A porcentagem de canários para cada fase é fornecido na variável de ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    A porcentagem de implantação associada a essa operação. Se o A variável de ambiente CLOUD_DEPLOY_FEATURES está definida como CANARY, 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 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 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:

  • (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 na execução do job para essa 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 de todos os metadados que você quer incluir

    O 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 logs de renderização da versão do Cloud Build.

Exemplo de arquivo de resultados de 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 as ações personalizadas

Confira alguns pontos a serem considerados ao configurar e usar tipos de segmentação personalizados.

Como executar as ações personalizadas

Suas ações de renderização e implantação personalizadas são executadas no ambiente de execução do Cloud Deploy. 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. Isso permite usar ações personalizadas definidas e armazenadas em um único local compartilhado, em vez de incluir as ações personalizadas com cada arquivo skaffold.yaml das versões.

Segmentações e estratégias de implantação personalizadas

Os destinos personalizados são totalmente compatíveis com padrão.

O Cloud Deploy oferece suporte a implantações canário, desde que o renderizador e o implantador personalizados ofereçam suporte ao recurso canário.

Use a configuração de canário personalizada. Automatizado e personalizado canários não são aceitos.

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

É possível usar parâmetros de implantação com segmentos 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 transmitidos aos contêineres de renderização e implantação personalizados 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 início rápido.

Esses exemplos não são um produto do Google Cloud com suporte e não são abrangidos 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