Crie um alvo personalizado

Este documento descreve como criar um tipo de destino do Cloud Deploy personalizado e usar esse tipo de destino personalizado como um destino num pipeline de entrega do Cloud Deploy.

Segue-se o processo de nível superior para criar um tipo de alvo personalizado e usá-lo no seu pipeline de fornecimento:

  1. Crie uma aplicação contentorizada ou aplicações que incluam a funcionalidade de implementação no seu alvo personalizado e que cumpram os requisitos do Cloud Deploy para tipos de alvos personalizados.

  2. Defina uma ação personalizada em skaffold.yaml que faça referência a esse contentor e especifique o comando ou os comandos a executar no mesmo.

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

  4. Defina um novo alvo com uma propriedade customTarget que identifica o seu novo tipo de alvo personalizado.

  5. Faça referência a essa segmentação a partir da progressão da sua pipeline de fornecimento.

  6. Crie um lançamento.

Cada um destes passos é descrito detalhadamente no resto deste documento.

Crie as suas aplicações contentorizadas

A funcionalidade de implementação no destino personalizado é definida em aplicações em contentores, que fornece ao Cloud Deploy fazendo referência às mesmas a partir do ficheiro skaffold.yaml. Quando a pipeline de implementação inclui um destino que usa um tipo de destino personalizado, o Cloud Deploy chama os contentores de ações personalizadas definidos para esse tipo de destino personalizado, no Skaffold, para executar as ações de renderização e implementação que definiu.

O comportamento das suas aplicações depende de si. No entanto, tem de consumir as variáveis de ambiente de entrada fornecidas pelo Cloud Deploy e devolver as saídas necessárias.

Na maioria dos casos, cria um contentor para a ação de renderização e um para a ação de implementação, para cada tipo de segmentação personalizada que criar. A ação de renderização é opcional, mas, se não fornecer uma, o Cloud Deploy usa a predefinição skaffold render.

Defina as suas ações personalizadas no Skaffold

Com a imagem ou as imagens do contentor de ação personalizada no lugar, faz referência às mesmas a partir do ficheiro de configuração skaffold.yaml.

Configura cada ação personalizada para um alvo personalizado numa secção customActions. Para qualquer tipo de segmentação personalizada, cria uma ação personalizada, no Skaffold, para a renderização e outra para a implementação. A definição CustomTargetType identifica a ação personalizada usada para a renderização e a ação usada para a implementação.

Segue-se a configuração para ações de renderização e implementaçã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 implementação personalizada. A definição de CustomTargetType faz referência a este nome na propriedade renderAction ou na propriedade deployAction.

  • A secção containers inclui a sua referência, além de comandos para executar esse contentor.

    A secção containers permite mais do que um contentor, mas a Google recomenda que use apenas um.

  • customActions.containers.name

    É um nome arbitrário para o contentor específico que está a usar para esta ação. Como prática recomendada, o nome deste contentor deve ser sempre qualificado com SHA.

  • image

    É o caminho para a imagem do contentor.

  • command

    É o comando ou os comandos a executar no contentor.

  • args

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

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

Defina o tipo de segmentação personalizada

Primeiro, defina um objetivo personalizado criando um tipo de objetivo personalizado através da configuração CustomTargetType. Pode criar o CustomTargetType no mesmo ficheiro que a definição do pipeline de entrega, ou com definições de destino, ou num ficheiro separado.

A definição de CustomTargetType é a seguinte:

# Custom target type config
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 atribui a esta definição de tipo de segmentação personalizada. Este nome é referenciado na definição do alvo para qualquer alvo que use o tipo de alvo personalizado que está a definir.

  • RENDER_ACTION_NAME

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

  • DEPLOY_ACTION_NAME

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

  • includeSkaffoldModules

    É uma secção opcional a usar se estiver a usar configurações do Skaffold remotas. As propriedades nesta secção são apresentadas na secção Usar configurações remotas do Skaffold.

Use configurações remotas do Skaffold

Pode armazenar configurações do Skaffold num repositório Git público, num contentor do Cloud Storage ou num repositório de 2.ª geração do Cloud Build e referenciar essas configurações a partir da definição do tipo de destino personalizado.

A utilização de configurações do Skaffold remotas significa que o skaffold.yaml que fornece no momento do lançamento não tem de ter as ações personalizadas definidas. Isto permite a partilha de ações personalizadas na sua organização.

Para usar configurações do Skaffold remotas:

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

  2. Armazene a configuração num repositório Git ou num contentor do Cloud Storage.

  3. Na definição do tipo de alvo personalizado, adicione uma secção 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 incluir. Se for omitido, o Cloud Deploy usa todas as configurações no caminho especificado.

    • Uma secção 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

      Onde:

      PATH_TO_GCS_BUCKET é o caminho para um diretório do Cloud Storage que termina com /*, onde as configurações do Skaffold estão armazenadas. O Skaffold transfere todos os ficheiros neste diretório e, em seguida, encontra o ficheiro do 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 onde as configurações do Skaffold estão armazenadas. O caminho assume o seguinte formato: projects/{project}/locations/{location}/connections/{connection}/repositories/{repository}. O Skaffold transfere todos os ficheiros neste diretório e, em seguida, encontra o ficheiro Skaffold com base no caminho relativo configurado.

      FILENAME é o nome do ficheiro que inclui as configurações do Skaffold. Esta propriedade path: é opcional. Se não a especificar, o Cloud Deploy assume skaffold.yaml. Se não existir nenhum elemento skaffold.yaml ou se o nome do ficheiro especificado não existir, a criação do lançamento falha.

      REPO_URL é o URL do repositório Git.

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

      BRANCH_NAME é o nome da ramificação (por exemplo, main) a partir da qual devem ser retiradas as configurações do Skaffold.

Exemplo

O YAML de tipo de destino personalizado seguinte é uma secção customActions com uma secção includeSkaffoldModules, que aponta para as configurações do Skaffold armazenadas num contentor 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 seguinte é uma configuração do Skaffold, à qual a ação personalizada apresentada faz referência:

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

Registe o seu tipo de segmentação personalizado

Depois de configurar o CustomTargetType, execute o comando gcloud deploy apply para registar o recurso CustomTargetType num projeto Google Cloud :

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

Onde:

FILE é o nome do ficheiro no qual definiu este tipo de segmentação personalizada.

PROJECT é o Google Cloud projeto no qual criar este recurso. O CustomTargetType tem de estar no mesmo projeto que o recurso Target que o referencia. Não precisa de especificar o projeto se o tiver definido como o projeto predefinido para a CLI do Google Cloud.

REGION é a região (por exemplo, us-centra1) na qual criar este recurso. O CustomTargetType tem de estar na mesma região que o recurso Target que faz referência ao mesmo. Não tem de especificar a região se a tiver definido como a região predefinida para a CLI gcloud.

Com o CustomTargetType agora criado como um recurso do Cloud Deploy, pode usá-lo numa definição Target para criar o seu destino personalizado.

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

Defina o seu alvo

A única diferença entre uma definição de alvo para um tipo de alvo suportado e uma definição de alvo personalizada é que a definição de alvo personalizada inclui uma secção customTarget. A sintaxe de um customTarget é a seguinte:

customTarget:
  customTargetType: [CUSTOM_TARGET_TYPE_NAME]

Onde CUSTOM_TARGET_TYPE_NAME é o valor da propriedade name definida na sua configuração do tipo de segmentação personalizada.

Adicione o alvo ao pipeline de fornecimento

Pode usar um alvo personalizado num pipeline de fornecimento exatamente como usaria um tipo de alvo suportado. Ou seja, não existe diferença na progressão do pipeline de fornecimento entre os alvos de um tipo de alvo suportado e os alvos personalizados.

Todos os alvos num pipeline de entrega têm de usar o mesmo tipo de alvo. Por exemplo, não pode ter um pipeline de implementação com alguns destinos a serem implementados no Google Kubernetes Engine e alguns destinos personalizados.

Tal como nos tipos de alvos suportados, pode incluir parâmetros de implementação na fase do pipeline.

Crie um lançamento

Com o tipo de alvo personalizado totalmente definido e um alvo criado para usar esse tipo, já pode criar um lançamento da forma normal:

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

Após a criação do lançamento, a ação de renderização personalizada é executada para cada destino no pipeline de fornecimento, incluindo o processamento dos parâmetros de implementação configurados no lançamento, nos destinos ou no pipeline de fornecimento. O Cloud Deploy fornece os parâmetros de implementação como entrada para o contentor de renderização personalizado.

Veja o resultado das suas segmentações personalizadas

Se a sua ação personalizada satisfizer os requisitos para alvos personalizados, pode usar a consola Google Cloud para ver os artefactos renderizados.

Siga estes passos para ver o resultado da sua ação de renderização personalizada.

  1. Na Google Cloud consola, navegue para a página do Cloud Deploy Pipelines de fornecimento para ver o seu pipeline de fornecimento.

    Abra a página Pipelines de fornecimento

  2. Clique no nome do pipeline de entrega.

    A visualização do pipeline mostra o estado de implementação da app e a versão é apresentada no separador Versões em Detalhes do pipeline de fornecimento.

  3. Clique no nome da versão.

    É apresentada a página Detalhes do lançamento.

  4. Clique no separador Artefactos.

  5. Em Artefactos de destino, clique na seta junto a Ver artefactos.

    Os artefactos renderizados são apresentados, incluindo o ficheiro de manifesto renderizado skaffold.yaml e o ficheiro de manifesto renderizado gerado pelo renderizador personalizado. Além disso, pode clicar no link Localização de armazenamento junto a cada um para aceder ao contentor do Cloud Storage e ver esses ficheiros.

    Também pode clicar no link Ver artefactos para ver esses ficheiros por versão, por destino ou por fase, através do inspetor de versões.

O que se segue?