Neste documento, descrevemos como criar um tipo de destino personalizado do Cloud Deploy e usá-lo como um destino em um pipeline de entrega do Cloud Deploy.
Confira a seguir o processo de alto nível para criar um tipo de destino personalizado e usá-lo no pipeline de entrega:
Crie um aplicativo conteinerizado ou aplicativos que incluam a funcionalidade de implantação no destino personalizado e que atendam aos requisitos do Cloud Deploy para tipos de destino personalizados.
Defina uma ação personalizada em
skaffold.yaml
que faça referência a esse contêiner e especifique os comandos a serem executados nele.Crie uma definição de
CustomTargetType
que faça referência à ação personalizada da etapa anterior e registre-a como um recurso do Cloud Deploy.Defina uma nova meta com uma propriedade
customTarget
que identifique seu novo tipo de segmentação personalizada.Faça referência ao destino da progressão do pipeline de entrega.
Cada uma dessas etapas é descrita em detalhes no restante deste documento.
Crie seus aplicativos conteinerizados
A funcionalidade a ser implantada no destino personalizado é definida em aplicativos conteinerizados, que você fornece ao Cloud Deploy
referenciando-os a partir do 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 de destino personalizado, no Skaffold, para executar as ações de renderização e implantação que você definiu.
O comportamento dos seus aplicativos 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ê cria um contêiner para a 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 usará o
skaffold render
padrão.
Definir ações personalizadas no Skaffold
Com as imagens ou imagens de contêiner de ação personalizada no local, referencie-as no arquivo de configuração skaffold.yaml
.
Você configura cada ação personalizada para um destino personalizado em uma estrofe 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 CustomTargetType
identifica qual ação personalizada é usada para renderização e qual é usada para implantação.
Esta é a configuração das ações personalizadas de renderização e implantação 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 personalizada de renderização ou implantação. A definição
CustomTargetType
faz referência a esse nome na propriedaderenderAction
oudeployAction
.A estrofe
containers
inclui sua referência e os comandos para executar esse contêiner.A estrofe
containers
permite mais de um contêiner, mas o Google recomenda que você use 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, esse nome de contêiner deve sempre ter qualificação SHA.
image
É o caminho para a imagem do contêiner.
command
São os comandos a serem executados no contêiner.
args
É uma coleção de argumentos para o
command
.
Consulte a referência YAML do Skaffold
para documentação detalhada sobre as propriedades de configuração usadas em
customActions
.
Defina seu 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ê dá para essa definição de tipo de destino personalizado. Esse nome é referenciado na definição de destino para qualquer destino que use o tipo de destino personalizado que você estiver definindo.
RENDER_ACTION_NAME
É o nome da ação de renderização personalizada. Esse valor é o
customAction.name
definido emskaffold.yaml
para a ação de renderização.DEPLOY_ACTION_NAME
É o nome da ação de implantação personalizada. Esse valor é o
customAction.name
definido emskaffold.yaml
para a ação deploy.includeSkaffoldModules
É uma estrofe opcional para usar se você estiver usando configurações remotas do Skaffold. As propriedades dessa 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 Git público, um bucket do Cloud Storage ou um repositório do Cloud Build de 2a geração e fazer referência a essas configurações na definição de 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 o compartilhamento de ações personalizadas em toda a organização.
Para usar as configurações remotas do Skaffold:
Crie uma configuração do Skaffold com ações personalizadas.
Armazene a configuração em um repositório Git ou em um bucket do Cloud Storage.
Na definição do tipo de segmentação personalizada, adicione uma estrofe
customActions.includeSkaffoldModules
.Em
includeSkaffoldModules
, especifique o seguinte:Opcionalmente, um ou mais elementos
configs
:- configs: ["name1", "name2"]
O valor de
configs
é uma lista de strings que correspondem à propriedademetadata.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 de
googleCloudStorage
,git
ougoogleCloudBuildRepo
.Para o Cloud Storage:
googleCloudStorage: source: PATH_TO_GCS_BUCKET path: FILENAME
Para Git:
git: repo: REPO_URL path: PATH_TO_FILE ref: BRANCH_NAME
Para repositórios do Cloud Build (2a 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, terminando com/*
, em que as configurações do Skaffold são armazenadas. O Skaffold faz o download de todos os arquivos nesse diretório e, em seguida, 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 de 2a geração do Cloud Build 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 neste diretório e, em seguida, encontra o arquivo Skaffold, com base no caminho relativo configurado.FILENAME
é o nome do arquivo que inclui as configurações do Skaffold. Essa propriedadepath:
é opcional. Se você não a especificar, o Cloud Deploy vai presumirskaffold.yaml
. Se não houverskaffold.yaml
ou se o nome de arquivo especificado não estiver lá, a criação da versão falhará.REPO_URL
é o URL do repositório Git.PATH_TO_FILE
é o caminho nesse 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 as configurações do Skaffold serão extraídas.
Exemplo
O seguinte YAML de tipo de destino personalizado é uma estrofe customActions
com uma estrofe includeSkaffoldModules
, apontando para 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, referenciada pela ação personalizada mostrada:
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 seu 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 segmentação personalizada.
PROJECT
é o projeto do Google Cloud em que o recurso será criado.
O CustomTargetType
precisa estar no mesmo projeto que o recurso Target
que o referencia. Não será necessário especificar o projeto se você o tiver 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 faz referência a ele. Não é necessário especificar a região se você a
definiu como padrão para a CLI gcloud.
Com o CustomTargetType
criado como um recurso do Cloud Deploy,
é possível usá-lo em uma definição de Target
para criar 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 sua meta
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 ela inclui uma
estrofe customTarget
. A sintaxe de um customTarget
é a seguinte:
customTarget:
customTargetType: [CUSTOM_TARGET_TYPE_NAME]
Em que CUSTOM_TARGET_TYPE_NAME
é o valor da propriedade name
definida na configuração do tipo de destino personalizado.
Adicionar o destino ao pipeline de entrega
É possível usar um destino personalizado em um pipeline de entrega exatamente como 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 alguns destinos implantados no Google Kubernetes Engine e outros personalizados.
Assim como nos tipos de destino compatíveis, é possível incluir parâmetros de implantação no estágio do pipeline.
Criar uma versão
Com o tipo de destino personalizado totalmente definido e um destino criado 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, a ação de renderização personalizada é executada para cada destino no pipeline de entrega, incluindo o processamento dos 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 personalizado.
Conferir a saída das segmentações personalizadas
Se a ação personalizada atender aos requisitos de destinos personalizados, use o console do Google Cloud para visualizar os artefatos renderizados.
Siga estas etapas para conferir o resultado da sua ação de renderização personalizada.
No console do Google Cloud, navegue até a página Pipelines de entrega do Cloud Deploy para visualizar o pipeline de entrega.
Clique no nome do pipeline de entrega.
A visualização do pipeline mostra o status de implantação do aplicativo, e a versão é listada na guia Versões em Detalhes do pipeline de entrega.
Clique no nome da versão.
A página Detalhes da versão é exibida.
Clique na guia Artefatos.
Em Artefatos de destino, clique na seta ao lado de Exibir artefatos.
Os artefatos renderizados são listados, incluindo o
skaffold.yaml
renderizado e o arquivo de manifesto renderizado gerado pelo renderizador personalizado. E você pode clicar no link Local de armazenamento ao lado de cada um para acessar o bucket do Cloud Storage e visualizar esses arquivos.Também é possível clicar no link Exibir artefatos para ver esses arquivos por versão, por destino ou por fase usando o Inspetor de versão.
A seguir
Confira o guia de início rápido: definir e usar um tipo de destino personalizado
Confira os exemplos de tipos de segmentações personalizadas disponíveis.
Saiba mais sobre como configurar destinos do Cloud Deploy.