Criar um destino personalizado

Este documento descreve como criar um tipo de destino personalizado do Cloud Deploy e usá-lo como destino em um pipeline de entrega do Cloud Deploy.

Confira a seguir o processo geral para criar um tipo de segmentação personalizada e usá-lo no pipeline de entrega:

1. Crie um aplicativo contêinerizado ou aplicativos que incluam a funcionalidade para implantar no destino personalizado e que atendam aos requisitos do Cloud Deploy para tipos de destino personalizados.

2. Defina uma ação personalizada em skaffold.yaml que refira esse contêiner e especifique os comandos a serem executados nele.

3. Crie uma definição CustomTargetType que faça referência à ação personalizada da etapa anterior e registre-a como um recurso do Cloud Deploy.

4. Defina uma nova meta com uma propriedade customTarget que identifique seu novo tipo de meta personalizada.

5. Referência a esse destino da progressão do pipeline de entrega.

6. Crie uma versão.

Cada uma dessas etapas é descrita em detalhes no restante deste documento.

Criar aplicativos conteinerizados

A funcionalidade para implantar no destino personalizado é definida em aplicativos conteinerizados, que você fornece ao Cloud Deploy fazendo referência a eles no arquivo skaffold.yaml. Quando o pipeline de entrega inclui um destino que usa um tipo de destino personalizado, o Cloud Deploy chama os contêineres de ação personalizada definidos para esse tipo no Skaffold para executar as ações de renderização e implantação que você definiu.

O comportamento dos seus apps depende de você. No entanto, ele precisa consumir as variáveis de ambiente de entrada fornecidas pelo Cloud Deploy e retornar as saídas necessárias.

Na maioria dos casos, você vai criar um contêiner para sua ação de renderização e outro para a ação de implantação, para cada tipo de destino personalizado criado. A ação de renderização é opcional, mas, se você não fornecer uma, o Cloud Deploy vai usar o skaffold render padrão.

Definir suas ações personalizadas no Skaffold

Com a imagem do contêiner de ação personalizada no lugar, você faz referência a ela no arquivo de configuração skaffold.yaml.

Você configura cada ação personalizada para um destino personalizado em um verso customActions. Para qualquer tipo de destino personalizado, você cria uma ação personalizada no Skaffold para renderização e outra para implantação. A definição de CustomTargetType identifica qual ação personalizada é usada para renderização e qual é usada para implantação.

Observação: o renderizador personalizado não é necessário se o destino personalizado puder usar o manifesto gerado pelo renderizador padrão (skaffold render). Em quase todos os casos, você vai precisar de uma ação de renderização personalizada.

Confira a seguir a configuração para ações de renderização e implantação personalizadas em skaffold.yaml:

apiVersion: skaffold/v4beta7
kind: Config
customActions:
# custom render action
- name:
  containers:
  - name:
    image:
    command:
    args:
# custom deploy action
- name:
  containers:
  - name:
    image:
    command:
    args:

Nesta configuração do Skaffold:

• customActions.name

  É um nome arbitrário para a ação de renderização ou implantação personalizada. A definição CustomTargetType faz referência a esse nome na propriedade renderAction ou deployAction.

• A estrofe containers inclui sua referência, além de comandos para executar esse contêiner.

  A estrofe containers permite mais de um contêiner, mas o Google recomenda usar apenas um.

• customActions.containers.name

  É um nome arbitrário para o contêiner específico que você está usando para essa ação. Como prática recomendada, o nome do contêiner deve sempre ser qualificado com SHA.

• image

  É o caminho para a imagem do contêiner.

• command

  É o comando ou os comandos a serem executados no contêiner.

• args

  É uma coleção de argumentos para o command.

Consulte a referência do YAML do Skaffold para conferir uma documentação detalhada sobre as propriedades de configuração usadas em customActions.

Observação: você também pode definir configurações do Skaffold e armazená-las em um repositório do Git ou em um bucket do Cloud Storage e fazer referência a essas configurações na definição do tipo de destino personalizado.

Definir o tipo de segmentação personalizada

Para definir um destino personalizado, primeiro crie um tipo de destino personalizado usando a configuração CustomTargetType. É possível criar o CustomTargetType no mesmo arquivo que a definição do pipeline de entrega, com definições de destino ou em um arquivo separado.

A definição de CustomTargetType é a seguinte:

# Custom target type config (preview)
apiVersion: deploy.cloud.google.com/v1
kind: CustomTargetType
metadata:
  name: [CUSTOM_TARGET_TYPE_NAME]
  annotations:
  labels:
description:
customActions:
  renderAction: [RENDER_ACTION_NAME]
  deployAction: [DEPLOY_ACTION_NAME]
  includeSkaffoldModules:

Onde

• CUSTOM_TARGET_TYPE_NAME

  É um nome arbitrário que você atribui a essa definição de tipo de destino personalizado. Esse nome é referenciado na definição de meta de qualquer meta que use o tipo de meta personalizada que você está definindo.

• RENDER_ACTION_NAME

  É o nome da ação de renderização personalizada. Esse valor é o customAction.name definido em skaffold.yaml para a ação render.

• DEPLOY_ACTION_NAME

  É o nome da ação de implantação personalizada. Esse valor é o customAction.name definido em skaffold.yaml para a ação deploy.

• includeSkaffoldModules

  É uma estrofe opcional para usar se você estiver usando configurações remotas do Skaffold. As propriedades nesta estrofe são mostradas na seção Usar configurações remotas do Skaffold.

Usar configurações remotas do Skaffold

É possível armazenar as configurações do Skaffold em um repositório público do Git, um bucket do Cloud Storage ou um repositório do Cloud Build de 2ª geração e fazer referência a essas configurações na definição do tipo de destino personalizado.

O uso de configurações remotas do Skaffold significa que o skaffold.yaml fornecido no momento da versão não precisa ter as ações personalizadas definidas. Isso permite compartilhar ações personalizadas em toda a organização.

Para usar as configurações remotas do Skaffold:

1. Crie uma configuração do Skaffold com suas ações personalizadas.

2. Armazene a configuração em um repositório do Git ou em um bucket do Cloud Storage.

3. Na definição do tipo de segmentação personalizada, adicione uma estrofe customActions.includeSkaffoldModules.

4. Em includeSkaffoldModules, especifique o seguinte:

   • Opcionalmente, um ou mais elementos configs:

     - configs: ["name1", "name2"]

     O valor de configs é uma lista de strings que correspondem à propriedade metadata.name em cada configuração do Skaffold a ser incluída. Se isso for omitido, o Cloud Deploy vai usar todas as configurações no caminho especificado.

   • Uma estrofe googleCloudStorage, git ou googleCloudBuildRepo.

     Para o Cloud Storage:

     googleCloudStorage:
       source: PATH_TO_GCS_BUCKET
       path: FILENAME
     

     Para o Git:

     git:
       repo: REPO_URL
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Para repositórios do Cloud Build (2ª geração):

      googleCloudBuildRepo:
       repository: PATH_TO_GCB_REPO
       path: PATH_TO_FILE
       ref: BRANCH_NAME
     

     Em que:

     PATH_TO_GCS_BUCKET é o caminho para um diretório do Cloud Storage, que termina com /*, onde as configurações do Skaffold são armazenadas. O Skaffold faz o download de todos os arquivos nesse diretório e encontra o arquivo Skaffold relevante com as configurações, com base no caminho relativo configurado.

     PATH_TO_GCB_REPO é o caminho para o repositório do Cloud Build de 2ª geração, em que as configurações do Skaffold são armazenadas. O caminho tem o seguinte formato: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. O Skaffold faz o download de todos os arquivos nesse diretório e encontra o arquivo com base no caminho relativo configurado.

     FILENAME é o nome do arquivo que inclui as configurações do Skaffold. Essa propriedade path: é opcional. Se você não a especificar, o Cloud Deploy vai assumir skaffold.yaml. Se não houver skaffold.yaml ou se o nome de arquivo especificado não estiver presente, a criação da versão vai falhar.

     REPO_URL é o URL do repositório Git.

     PATH_TO_FILE é o caminho no repositório para o arquivo que contém as configurações do Skaffold.

     BRANCH_NAME é o nome da ramificação (por exemplo, main) de onde extrair as configurações do Skaffold.

Exemplo

O YAML de tipo de destino personalizado a seguir é uma estrofe customActions com uma includeSkaffoldModules, que aponta para as configurações do Skaffold armazenadas em um bucket do Cloud Storage:

customActions:
  renderAction: my-custom-action
  deployAction: my-custom-action
  includeSkaffoldModules:
    - configs: ["myConfig"]
      googleCloudStorage:
        source: "gs://my-custom-target-bucket/my-custom/*"
        path: "skaffold.yaml

O YAML a seguir é uma configuração do Skaffold, que a ação personalizada mostrada está referenciando:

apiVersion: skaffold/v4beta7
kind: Config
metadata:
  name: myConfig
customActions:
  - name: my-custom-action
    containers:
      - name: my-custom-container
        image: us-east1-docker.pkg.dev/abcdefg/foldername/myimage@sha256:c56fcf6e0a7637ddf0df3d56a0dd23bfce03ceca06a6fc527b0e0e7430e6e9f9

Registrar o tipo de segmentação personalizada

Depois de configurar o CustomTargetType, execute o comando gcloud deploy apply para registrar o recurso CustomTargetType em um projeto do Google Cloud:

gcloud deploy apply --file=[FILE] --project=[PROJECT] --region=[REGION]

Em que:

FILE é o nome do arquivo em que você definiu esse tipo de destino personalizado.

PROJECT é o projeto do Google Cloud em que esse recurso será criado. O CustomTargetType precisa estar no mesmo projeto que o recurso Target que o referencia. Não é necessário especificar o projeto se ele tiver sido definido como o projeto padrão para a Google Cloud CLI.

REGION é a região (por exemplo, us-centra1) em que esse recurso será criado. O CustomTargetType precisa estar na mesma região que o recurso Target que o referencia. Não é necessário especificar a região se você a definiu como a região padrão para a CLI gcloud.

Com o CustomTargetType criado como um recurso do Cloud Deploy, agora é possível usá-lo em uma definição de Target para criar o destino personalizado.

Para mais informações sobre a definição de CustomTargetType, consulte a referência do esquema de configuração do Cloud Deploy.

Definir o destino

A única diferença entre uma definição de destino para um tipo de destino compatível e uma definição de destino personalizada é que a definição de destino personalizada inclui uma estrofe customTarget. A sintaxe de customTarget é a seguinte:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Em que CUSTOM_TARGET_TYPE_NAME é o valor da propriedade name definida na sua configuração de tipo de destino personalizado.

Observação: é possível usar vários destinos quando os destinos filhos são personalizados. Nesse caso, todas as segmentações filhas precisam ser do mesmo CustomTargetType.

Adicionar o destino ao pipeline de entrega

É possível usar um destino personalizado em um pipeline de entrega exatamente como você usaria um tipo de destino compatível. Ou seja, não há diferença na progressão do pipeline de entrega entre destinos de um tipo de destino compatível e destinos personalizados.

Todos os destinos em um pipeline de entrega precisam usar o mesmo tipo. Por exemplo, não é possível ter um pipeline de entrega com algumas metas implantadas no Google Kubernetes Engine e algumas metas personalizadas.

Assim como nos tipos de destino compatíveis, é possível incluir parâmetros de implantação na fase do pipeline.

Criar uma versão

Observação: se você não estiver usando as configurações remotas do Skaffold, o arquivo skaffold.yaml fornecido para a versão precisa definir as ações personalizadas que o tipo de destino personalizado exige.

Com o tipo de segmentação personalizada totalmente definido e uma segmentação criada para usar esse tipo, agora é possível criar uma versão da maneira normal:

gcloud deploy releases create [RELEASE_NAME] \
  --project=[PROJECT_NAME] \
  --region=[REGION] \
  --delivery-pipeline=[PIPELINE_NAME]

Após a criação da versão, sua ação de renderização personalizada é executada para cada destino no pipeline de entrega, incluindo o processamento de parâmetros de implantação configurados na versão, nos destinos ou no pipeline de entrega. O Cloud Deploy fornece os parâmetros de implantação como entrada para o contêiner de renderização personalizada.

Conferir a saída das segmentações personalizadas

Se a ação personalizada atender aos requisitos para segmentos personalizados, use o console do Google Cloud para conferir os artefatos renderizados.

Siga estas etapas para conferir a saída da sua ação de renderização personalizada.

1. No console do Google Cloud, acesse a página Pipelines de entrega do Cloud Deploy para conferir seu pipeline de entrega.

   Abrir a página "Pipelines de entrega"

2. Clique no nome do pipeline de entrega.

   A visualização do pipeline mostra o status de implantação do app, e a versão é listada na guia Versões em Detalhes do pipeline de entrega.

3. Clique no nome da versão.

   A página Detalhes da versão é mostrada.

4. Clique na guia Artefatos.

5. Em Artefatos de destino, clique na seta ao lado de Ver artefatos.

   Os artefatos renderizados são listados, incluindo o skaffold.yaml renderizado e o arquivo de manifesto renderizado gerado pelo renderizador personalizado. Você pode clicar no link Local de armazenamento ao lado de cada um para acessar o bucket do Cloud Storage e conferir os arquivos.

   Também é possível clicar no link Ver artefatos para conferir esses arquivos por versão, destino ou fase usando o inspetor de versão.

A seguir

• Teste o guia de início rápido: definir e usar um tipo de destino personalizado.

• Confira os exemplos de tipos de destino personalizados disponíveis.

• Crie um pipeline de entrega e destinos.

• Saiba mais sobre como configurar destinos do Cloud Deploy