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"