Acerca das segmentações personalizadas

Este documento descreve como funcionam os destinos personalizados no Cloud Deploy.

O Cloud Deploy inclui suporte integrado para vários ambientes de tempo de execução como alvos. No entanto, a lista de tipos de segmentação suportados é finita. Com as segmentações personalizadas, pode implementar noutros sistemas além dos tempos de execução suportados.

Um destino personalizado é um destino que representa um ambiente de saída arbitrário que não seja um tempo de execução suportado pelo Cloud Deploy.

A página Crie um alvo personalizado descreve o processo de definição de um tipo de alvo personalizado e a respetiva implementação como alvo num pipeline de entrega.

O que é preciso para criar um alvo personalizado?

Cada alvo personalizado é composto pelos seguintes componentes:

  • Ações personalizadas, definidas em skaffold.yaml

    São semelhantes à forma como define os hooks de implementação. No ficheiro skaffold.yaml, define customActions, em que cada ação personalizada identifica uma imagem de contentor a usar e comandos a executar nesse contentor.

    Desta forma, a segmentação personalizada é simplesmente uma ação ou um conjunto de ações definidas de forma personalizada.

    Para qualquer tipo de segmentação personalizada, configura uma ação de renderização personalizada e uma ação de implementação personalizada. Estas ações consomem valores fornecidos pelo Cloud Deploy e têm de cumprir um conjunto de resultados necessários.

    A ação de renderização personalizada é opcional, mas tem de criar uma, a menos que o seu destino personalizado funcione corretamente se for renderizado por skaffold render, que é a predefiniçã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 no seu skaffold.yaml) que os destinos deste tipo usam para atividades de renderização de lançamentos e implementação de implementações.

  • Uma definição de alvo

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

Com esses componentes implementados, pode usar o destino como qualquer outro destino, fazendo referência ao mesmo a partir da progressão do pipeline de implementação e tirando o máximo partido das funcionalidades do Cloud Deploy, como a promoção e as aprovações, e as reversões.

Um exemplo

O início rápido Definir e usar um tipo de destino personalizado cria um tipo de destino personalizado que inclui comandos simples para executar numa imagem de contentor: um comando para renderização e outro para implementação. Os comandos, neste caso, apenas adicionam texto aos ficheiros de saída necessários para a renderização e a implementação.

Para ver mais exemplos, consulte Exemplos de alvos personalizados.

Entradas e saídas necessárias

Qualquer tipo de segmentação personalizada definido para a implementação na nuvem tem de satisfazer os requisitos de entrada e saída, tanto para a renderização como para a implementação. Esta secção indica as entradas e saídas necessárias, bem como a forma como são fornecidas.

O Cloud Deploy fornece as entradas necessárias, tanto para a renderização como para a implementação, como variáveis de ambiente. As secções seguintes listam estas entradas, bem como as saídas que as ações de renderização e implementação personalizadas têm de devolver.

Implemente parâmetros como variáveis de ambiente

Além das variáveis de ambiente indicadas nesta secção, o Cloud Deploy pode transmitir aos seus contentores personalizados quaisquer parâmetros de implementação que tenha definido.

Saiba mais.

Entradas para renderizar ações

Para ações de renderização personalizadas, o Cloud Deploy fornece as seguintes entradas como variáveis de ambiente. Para implementações em várias fases (implementações canary), o Cloud Deploy fornece estas variáveis para cada fase.

  • CLOUD_DEPLOY_PROJECT

    O Google Cloud número do projeto no qual o alvo personalizado é criado.

  • CLOUD_DEPLOY_PROJECT_ID

    O Google Cloud ID do projeto.

  • CLOUD_DEPLOY_LOCATION

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

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    O nome do pipeline de fornecimento do Cloud Deploy que faz referência ao tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    O nome do lançamento para o 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 implementação à qual a renderização corresponde.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para a ação de renderização personalizada, esta é sempre RENDER.

  • CLOUD_DEPLOY_FEATURES

    Uma lista separada por vírgulas de funcionalidades do Cloud Deploy que o contentor personalizado tem de suportar. Esta variável é preenchida com base nas funcionalidades configuradas no seu pipeline de entrega.

    Se a sua implementação não suportar as funcionalidades nesta lista, recomendamos que falhe durante a renderização.

    Para implementações padrão, este campo está vazio. Para implementações canary, o valor é CANARY. Se o valor fornecido pelo Cloud Deploy for CANARY, a ação de renderização é invocada para cada fase no teste canário. A percentagem de testes canários para cada fase é fornecida na variável de ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    A percentagem de implementação associada a esta operação de renderização. Se a variável de ambiente CLOUD_DEPLOY_FEATURES estiver definida como CANARY, a ação de renderização personalizada é chamada para cada fase, e esta variável é definida como a percentagem de teste canário para cada fase. Para implementações padrão e para implementações de teste que atingiram a fase stable, isto é 100.

  • CLOUD_DEPLOY_STORAGE_TYPE

    O fornecedor de armazenamento. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    O caminho do Cloud Storage para o arquivo do ficheiro de renderização escrito quando o lançamento foi criado.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    O caminho do Cloud Storage onde se espera que o contentor de renderização personalizado carregue artefactos a serem usados para a implementação. Tenha em atenção que a ação de renderização tem de carregar um ficheiro denominado results.json que contenha os resultados desta operação de renderização. Para mais informações, consulte o artigo Resultados da ação de renderização.

Resultados da ação de renderização

A sua ação de renderização personalizada tem de fornecer as informações descritas nesta secção. As informações têm de ser incluídas no ficheiro de resultados com o nome results.json, localizado no contentor do Cloud Storage fornecido pelo Cloud Deploy.

  • Ficheiro ou ficheiros de configuração renderizados

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

    • Uma indicação do estado de êxito ou falha da ação personalizada.

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

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

    • O caminho do Cloud Storage para o ficheiro de configuração renderizado ou os ficheiros.

      O caminho para todos os ficheiros de configuração renderizados é o URI completo. Preenche-o parcialmente com o valor de CLOUD_DEPLOY_OUTPUT_GCS_PATH fornecido pelo Cloud Deploy.

      Tem de fornecer o ficheiro de configuração renderizado, mesmo que esteja vazio. O conteúdo do ficheiro pode ser qualquer coisa, em qualquer formato, desde que seja consumível pela sua ação de implementação personalizada. Recomendamos que este ficheiro seja legível por humanos para que possa vê-lo, bem como outros utilizadores da sua organização, no inspetor de lançamentos.

    • (Opcional) Um mapa de quaisquer metadados que queira incluir

      O seu objetivo personalizado cria estes metadados. Estes metadados são armazenados na versão, no campo custom_metadata.

Se precisar de examinar o ficheiro results.json, por exemplo, para depuração, pode encontrar o URI do Cloud Storage no ficheiro nos registos do Cloud Build.

Exemplo de ficheiro de resultados de renderização

Segue-se um exemplo de um ficheiro results.json gerado por 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 implementar ações

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

  • CLOUD_DEPLOY_PROJECT

    O Google Cloud número do projeto no qual o alvo personalizado é criado.

  • CLOUD_DEPLOY_PROJECT_ID

    O Google Cloud ID do projeto.

  • CLOUD_DEPLOY_LOCATION

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

  • CLOUD_DEPLOY_DELIVERY_PIPELINE

    O nome do pipeline de implementação do Cloud Deploy que faz referência ao destino que usa o tipo de destino personalizado.

  • CLOUD_DEPLOY_RELEASE

    O nome do lançamento para o qual a operação de implementação é invocada.

  • CLOUD_DEPLOY_ROLLOUT

    O nome da implementação gradual do Cloud Deploy para a qual esta implementaçã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 implementação à qual a implementação corresponde.

  • CLOUD_DEPLOY_REQUEST_TYPE

    Para a ação de implementação personalizada, esta opção é sempre DEPLOY.

  • CLOUD_DEPLOY_FEATURES

    Uma lista separada por vírgulas de funcionalidades do Cloud Deploy que o contentor personalizado tem de suportar. Esta variável é preenchida com base nas funcionalidades configuradas no seu pipeline de entrega.

    Se a sua implementação não suportar as funcionalidades nesta lista, recomendamos que falhe durante a renderização.

    Para implementações padrão, este campo está vazio. Para implementações canary, o valor é CANARY. Se o valor fornecido pelo Cloud Deploy for CANARY, a ação de renderização é invocada para cada fase no teste canário. A percentagem de testes canários para cada fase é fornecida na variável de ambiente CLOUD_DEPLOY_PERCENTAGE_DEPLOY.

  • CLOUD_DEPLOY_PERCENTAGE_DEPLOY

    A percentagem de implementação associada a esta operação de implementação. Se a variável de ambiente CLOUD_DEPLOY_FEATURES estiver definida como CANARY, a ação de implementação personalizada é chamada para cada fase, e esta variável é definida como a percentagem de teste canário para cada fase. A ação de implementação tem de ser executada para cada fase.

  • CLOUD_DEPLOY_STORAGE_TYPE

    O fornecedor de armazenamento. Sempre GCS.

  • CLOUD_DEPLOY_INPUT_GCS_PATH

    O caminho do Cloud Storage onde o renderizador personalizado escreveu os ficheiros de configuração renderizados.

  • CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

    O caminho do Cloud Storage para a configuração do Skaffold renderizada.

  • CLOUD_DEPLOY_MANIFEST_GCS_PATH

    O caminho do Cloud Storage para o ficheiro de manifesto renderizado.

  • CLOUD_DEPLOY_OUTPUT_GCS_PATH

    O caminho para o diretório do Cloud Storage onde se espera que o contentor de implementação personalizado carregue artefactos de implementação. Para mais informações, consulte o artigo Resultados da ação de implementação.

Resultados da ação de implementação

A ação de implementação personalizada tem de escrever um ficheiro de saída results.json. Este ficheiro tem de estar localizado no contentor do Cloud Storage fornecido pelo Cloud Deploy (CLOUD_DEPLOY_OUTPUT_GCS_PATH).

O ficheiro tem de incluir o seguinte:

  • Uma indicação do estado de êxito ou falha da ação de implementação personalizada.

    Seguem-se os estados válidos:

    • SUCCEEDED

    • FAILED

    • SKIPPED

    Isto destina-se a implementações de teste em que as fases de teste são ignoradas, para passar diretamente para stable.

  • (Opcional) Uma lista de ficheiros de artefactos de implementação, no formato de caminhos do Cloud Storage

    O caminho é o URI completo. Preenche-o parcialmente com o valor CLOUD_DEPLOY_OUTPUT_GCS_PATH fornecido pelo Cloud Deploy.

    Os ficheiros apresentados aqui são preenchidos em recursos de execução de tarefas como artefatos de implementação.

  • (Opcional) Uma mensagem de falha, se a ação de implementação personalizada não for bem-sucedida (devolvendo um estado FAILED)

    Esta mensagem é usada para preencher o failure_message na execução da tarefa para esta ação de implementação.

  • (Opcional) Uma mensagem de ignorar para fornecer informações adicionais se a ação devolver um estado SKIPPED.

  • (Opcional) Um mapa de quaisquer metadados que queira incluir

    O seu objetivo personalizado cria estes metadados. Estes metadados são armazenados na execução da tarefa e na implementação, no campo custom_metadata.

Se precisar de examinar o ficheiro results.json, por exemplo, para depuração, pode encontrar o URI do Cloud Storage para o mesmo nos registos de renderização da versão do Cloud Build.

Exemplo de ficheiro de resultados da implementação

Segue-se um exemplo de um ficheiro results.json gerado por uma ação de implementaçã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 as ações personalizadas

Seguem-se alguns aspetos a ter em conta ao configurar e usar tipos de segmentação personalizados.

Executar as ações personalizadas

As ações de renderização e implementação personalizadas são executadas no ambiente de execução do Cloud Deploy. Não pode configurar as ações personalizadas para serem executadas num cluster do Google Kubernetes Engine.

Usar configurações do Skaffold remotas e reutilizáveis

Conforme descrito neste documento, configure a sua ação personalizada no ficheiro skaffold.yaml fornecido na criação do lançamento. No entanto, também pode armazenar configurações do Skaffold num repositório Git ou num contentor do Cloud Storage e fazer referência a elas a partir da definição do tipo de destino personalizado. Isto permite-lhe usar ações personalizadas definidas e armazenadas numa única localização partilhada, em vez de incluir as ações personalizadas no ficheiro skaffold.yaml de cada lançamento.

Alvos personalizados e estratégias de implementação

Os alvos personalizados são totalmente suportados para implementações padrão.

A implementação na nuvem suporta implementações canary, desde que o renderizador e o implementador personalizados suportem a funcionalidade canary.

Tem de usar a configuração canária personalizada. Os testes canários automatizados e personalizados automatizados não são suportados com alvos personalizados.

Alvos personalizados e parâmetros de implementação

Pode implementar parâmetros com segmentações personalizadas. Pode defini-los na fase do pipeline de fornecimento, no alvo que usa um tipo de alvo personalizado ou na versão.

Os parâmetros de implementação são transmitidos para os contentores de implementação e renderização personalizados, como variáveis de ambiente, além dos já fornecidos.

Exemplos de alvos personalizados

O repositório cloud-deploy-samples contém um conjunto de implementações de alvos personalizados de exemplo. Estão disponíveis os seguintes exemplos:

  • GitOps

  • Vertex AI

  • Terraform

  • Infrastructure Manager

  • Leme

Cada exemplo inclui um início rápido.

Estes exemplos não são um produto suportado Google Cloud e não estão cobertos por um Google Cloud contrato de apoio técnico. Para comunicar erros ou pedir funcionalidades num Google Cloud produto, contacte Google Cloud o apoio técnico.

O que se segue?