Implantar pacotes de frota

Nesta página, explicamos como usar pacotes de frota do Config Sync para implantar recursos do Kubernetes em clusters registrados em uma frota. Depois de criar e implantar um pacote de frota, quando você adiciona um novo cluster à frota, o pacote implanta automaticamente os arquivos de configuração do Kubernetes no repositório Git no novo cluster.

Um FleetPackage é uma API declarativa para implantar manifestos brutos do Kubernetes em uma frota de clusters. Todos os recursos do Kubernetes que você quer implantar com um pacote de frota precisam estar já hidratados (WET).

Antes de começar

1. Crie ou verifique se você tem acesso a um repositório Git com os recursos do Kubernetes que você quer implantar em uma frota.

2. Instale e inicialize a Google Cloud CLI, que fornece os comandos gcloud e nomos. Se você usa o Cloud Shell, a Google Cloud CLI já vem pré-instalada. Se você já instalou a Google Cloud CLI, instale a versão mais recente executando gcloud components update.

   Observação: para instalações atuais da CLI gcloud, defina as compute/region e compute/zone propriedades. Ao definir locais padrão, você evita erros como este na CLI gcloud: One of [--zone, --region] must be supplied: Please specify location.

3. Ative a API Config Sync (anthosconfigmanagement) e a API ConfigDelivery:

   gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com
   

4. Definir um local padrão:

   gcloud config set config_delivery/location us-central1
   

   Observação: o único local disponível para a API ConfigDelivery é us-central1.

5. Defina um projeto padrão:

   gcloud config set project PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do projeto host da frota.

6. Verifique se os clusters estão registrados em uma frota.

7. Use repositórios do Cloud Build para criar uma conexão com um provedor compatível, como GitHub ou GitLab. Quando você usa um pacote de frota, é necessário configurar o Cloud Build apenas uma vez por repositório que você quer sincronizar.

   Importante: sua conexão do Cloud Build precisa estar localizada em us-central1 porque a conexão do Git e FleetPackage precisam estar na mesma região. A API ConfigDelivery está disponível apenas em us-central1.

Revisar os requisitos do cluster

Antes de instalar o Config Sync no cluster, consulte as recomendações e requisitos de configuração do cluster.

Preparar o ambiente

Para preparar seu ambiente para pacotes de frota do Config Sync, conceda os papéis necessários do IAM ao usuário que registra o cluster.

Instalar o Config Sync

É possível instalar o Config Sync com o console Google Cloud ou a Google Cloud CLI.

Console

Para instalar o Config Sync, todos os clusters precisam estar registrados em uma frota. Ao instalar o Config Sync no console do Google Cloud , a seleção de clusters individuais os registra automaticamente na frota.

1. No console do Google Cloud , acesse a página Configuração na seção Recursos.

   Acessar a configuração

2. Clique em Instalar o Config Sync.

3. Em Opções de instalação, selecione Instalar o Config Sync em toda a frota (recomendado).

4. Clique em Instalar o Config Sync. Na guia Configurações, após alguns minutos, a mensagem Ativado vai aparecer na coluna Status dos clusters na sua frota.

gcloud

1. Ative o recurso de frota ConfigManagement:

   gcloud beta container fleet config-management enable
   

2. Para ativar o Config Sync, crie um arquivo chamado apply-spec.yaml com o seguinte conteúdo:

   applySpecVersion: 1
   spec:
     configSync:
       enabled: true
   

3. Aplique o arquivo apply-spec.yaml:

   gcloud beta container fleet config-management apply \
       --membership=MEMBERSHIP_NAME \
       --config=apply-spec.yaml
   

   Substitua MEMBERSHIP_NAME pelo nome da assinatura de frota que você escolheu ao registrar o cluster. Para encontrar o nome da assinatura, execute o comando gcloud container fleet memberships list.

Criar uma conta de serviço para o Cloud Build

Os pacotes da frota usam o Cloud Build para buscar os recursos do Kubernetes no seu repositório Git e implantar nos seus clusters. O Cloud Build exige uma conta de serviço com as permissões necessárias para executar esse job. Para criar a conta de serviço e conceder as permissões necessárias, siga estas etapas:

1. Crie a conta de serviço:

   gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
   

   Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço. O nome precisa ser um ID alfanumérico entre 6 e 30 caracteres, por exemplo, my-service-account. Depois de criar uma conta de serviço, não é possível alterar o nome dela.

2. Adicione uma vinculação de política do IAM para o papel de Editor do pacote de recursos:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/configdelivery.resourceBundlePublisher'
   

   Se solicitado, selecione None como a condição da política.

3. Adicione uma vinculação de política do IAM para o papel Gravador de registros:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/logging.logWriter'
   

   Se solicitado, selecione None como a condição da política.

4. Adicione uma vinculação de política do IAM para o papel Gravador do Artifact Registry:

   gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      --role='roles/artifactregistry.writer'
   

   Se solicitado, selecione None como a condição da política.

Criar um pacote de frota

Para criar um pacote de frota, defina uma especificação FleetPackage que aponte para o repositório com os recursos do Kubernetes conectados ao Cloud Build. Em seguida, aplique o FleetPackage, que busca os recursos do Git e os implanta na frota.

1. Crie um arquivo chamado fleetpackage-spec.yaml com o conteúdo a seguir:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
   target:
     fleet:
       project: projects/PROJECT_ID
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   # set the state to SUSPENDED to pause new rollouts
   # set the state back to ACTIVE to resume rollouts
   # state: SUSPENDED
   

   Substitua:

   • CONNECTION_NAME: o nome escolhido quando você conectou seu host Git ao Cloud Build. Para ver todas as conexões do Cloud Build no seu projeto, execute gcloud builds connections list ou abra a página Repositórios no console do Google Cloud :

     Abrir a página Repositórios

   • REPOSITORY_NAME: o nome do seu repositório Ele precisa ser idêntico ao valor inserido ao configurar a conexão do Cloud Build.

   • TAG: a tag do Git do seu repositório. O formato precisa ser a versão semântica completa com o número principal, secundário e de patch. Por exemplo, v1.0.0 é uma tag válida, enquanto v1 ou v1.0 são tags inválidas.

   • CONFIG_FILE_PATH: o caminho para os recursos do Kubernetes no repositório. Se os arquivos estiverem na raiz do repositório, você poderá omitir esse campo.

   • MAX_CLUSTERS: o número máximo de clusters para implantar recursos do Kubernetes de uma só vez. Por exemplo, se você definir como 1, os pacotes de recursos serão implantados em um cluster por vez.

     Para uma lista completa de todos os campos que podem ser configurados, consulte a documentação de referência do FleetPackage.

2. Crie o pacote de frota:

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Substitua FLEET_PACKAGE_NAME por um nome para o lançamento do pacote da frota.

3. Verifique se o pacote de frota foi criado:

   gcloud container fleet packages list
   

   A saída lista o status do gatilho de build. Após alguns segundos, o campo MESSAGE é atualizado com uma saída semelhante a esta:

   MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
   

   Clique no link fornecido para visualizar os logs de streaming do job do Cloud Build. O Cloud Build pode levar alguns minutos para processar o gatilho de build.

   Se o gatilho de build for bem-sucedido, o pacote de frota começará a lançar os recursos do Kubernetes na sua frota.

4. Quando o gatilho de build é concluído, a saída do gcloud container fleet packages list é semelhante ao seguinte:

   NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
   my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621
   

   O pacote de frota começa a lançar os recursos do Kubernetes na sua frota.

Agora que você implantou um pacote de frota, quando adicionar um novo cluster à sua frota, os recursos do Kubernetes definidos no pacote de frota serão implantados automaticamente no novo cluster.

Atualizar um pacote de frota

É possível atualizar um pacote da frota para mudar as configurações ou os recursos que ele implanta, como nos exemplos a seguir:

• Mude a estratégia de lançamento alterando o valor do campo maxConcurrent.
• Pause temporariamente um pacote de frota definindo state: SUSPENDED. Quando um pacote de frota é suspenso, todos os rollouts em andamento continuam. Nenhum novo lançamento será criado ou programado até que você mude o estado de volta para ACTIVE.
• Atualize os recursos do Kubernetes que o pacote da frota implanta atualizando o campo tag para extrair de uma tag do Git diferente.

Para atualizar um pacote da frota, siga estas etapas:

1. Atualize a especificação FleetPackage com suas mudanças.

2. Atualize o pacote da frota:

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Pode levar alguns minutos até que a mudança seja detectada e comece a ser lançada nos clusters.

Gerenciar lançamentos de pacotes da frota

É possível monitorar o progresso das implantações de pacotes da frota e gerenciar os rollouts ativos. Quando um pacote da frota é alterado, um novo lançamento é criado automaticamente. Os comandos a seguir ajudam você a receber informações detalhadas sobre implantações. Por exemplo, se você precisar depurar um problema de implantação, examine os detalhes do lançamento e pause ou cancele um lançamento, se necessário.

1. Ao listar um lançamento, você pode conferir o status de todos os lançamentos vinculados a um pacote, incluindo erros que podem causar falha. Para listar os lançamentos e ver o status deles, execute o seguinte comando:

   gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME
   

   A saída será assim:

   ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
   rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
   rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED
   

2. A descrição de um lançamento fornece informações detalhadas sobre um lançamento específico, incluindo o status de cada cluster segmentado e erros específicos do cluster. Para descrever uma implementação, execute o seguinte comando:

   gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
   

   Substitua ROLLOUT_NAME pelo nome do lançamento. É possível conseguir o nome completo do lançamento com o comando list na etapa anterior.

   A saída será assim:

   CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
   cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
   cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists
   

3. É possível gerenciar os lançamentos ativos executando os seguintes comandos:

   • A suspensão de um lançamento coloca um lançamento em andamento no estado SUSPENDED. As atualizações de pacotes em andamento continuam, e nenhuma outra atualização de pacote é programada. Para suspender um lançamento, execute o seguinte comando:

     gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

   • Retomar um lançamento muda um lançamento SUSPENDED de volta para um estado IN_PROGRESS. As atualizações de pacote são implantadas nos clusters de destino conforme o planejado. Para retomar um lançamento, execute o seguinte comando:

     gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

   • O cancelamento de um lançamento em andamento encerra imediatamente o lançamento, colocando-o em um estado ABORTED. Todas as atualizações de pacotes pendentes planejadas como parte do lançamento são canceladas. Para cancelar um lançamento, execute o seguinte comando:

     gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
     

Usar rótulos para fazer implantações em diferentes clusters

Rótulos são pares de chave-valor que você anexa a objetos. Os pacotes de frota só aceitam rótulos de associação de frota. Os rótulos de cluster do GKE não são compatíveis.

É possível usar rótulos para implantar um pacote de frota em um subconjunto de clusters na sua frota.

Adicionar marcadores de assinatura

Para adicionar um rótulo de assinatura, siga estas etapas:

1. Confira uma lista de associações na frota:

   gcloud container fleet memberships list
   

2. Adicione um rótulo à associação:

   gcloud container fleet memberships update MEMBERSHIP_NAME \
       --update-labels=KEY=VALUE
   

   Substitua:

   • MEMBERSHIP_NAME: o nome do cluster registrado na frota.
   • KEY e VALUE: o rótulo a ser adicionado à assinatura. Se um rótulo existir, o valor dele será modificado. Caso contrário, um novo rótulo será criado. As chaves precisam começar com uma letra minúscula e conter apenas hifens (-), sublinhados (_), letras minúsculas e números. Os valores precisam conter apenas hifens (-), sublinhados (_), caracteres minúsculos e números.

   Repita esse comando para cada assinatura a que você quer adicionar um rótulo.

Implantar em um subconjunto de clusters

É possível implantar em um subconjunto de clusters especificando o campo target.fleet.selector.matchLabels com seu par de chave-valor. Por exemplo, se você definir matchLabels como country: "us", o serviço de pacote da frota vai implantar seus recursos apenas em clusters com o rótulo country que corresponda a "us".

Para implantar um pacote da frota em um subconjunto de clusters, siga estas etapas:

1. Crie ou atualize a especificação FleetPackage com o seletor de rótulo:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
   target:
     fleet:
       project: projects/PROJECT_ID
       selector:
         matchLabels:
           KEY: "VALUE"
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   

2. Crie ou atualize o pacote de frota:

   Criar um pacote de frota

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Atualizar um pacote de frota

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

Implantar recursos de variantes em clusters

As variantes são versões diferentes de um recurso. Esses recursos podem ter valores diferentes dependendo do local, do projeto ou do nome do cluster. É possível implantar recursos de variantes em clusters diferentes especificando os campos variantsPattern e variantNameTemplate.

É possível usar rótulos de associação ou outros metadados, como local, projeto ou nome, para corresponder às variantes.

Para implantar um pacote de frota com variantes, siga estas etapas:

1. Crie ou atualize a especificação FleetPackage com os detalhes da variante:

   resourceBundleSelector:
     cloudBuildRepository:
       name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
       tag: TAG
       serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
       path: CONFIG_FILE_PATH
       variantsPattern: VARIANT_PATTERN
   target:
     fleet:
       project: projects/PROJECT_ID
   rolloutStrategy:
     rolling:
       maxConcurrent: MAX_CLUSTERS
   target:
     fleet:
       project: projects/PROJECT_ID
    variantSelector:
     variantNameTemplate: VARIANT_NAME_TEMPLATE
   

   Substitua:

   • VARIANT_PATTERN: o padrão da variante, por exemplo, "variants/*.yaml" ou "us-*".
   • VARIANT_NAME_TEMPLATE : uma string de modelo que se refere a variáveis que contêm metadados de assinatura de clusters, como local, projeto, nome ou rótulo, para determinar o nome da variante para um cluster de destino. Para mais exemplos, consulte a documentação de referência do FleetPackage.

2. Crie ou atualize o pacote de frota:

   Criar um pacote de frota

   gcloud container fleet packages create FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

   Atualizar um pacote de frota

   gcloud container fleet packages update FLEET_PACKAGE_NAME \
       --source=fleetpackage-spec.yaml
   

Excluir um pacote de frota

A exclusão de um pacote de frota também exclui os seguintes recursos:

• Os recursos do Kubernetes implantados nos seus clusters
• O histórico de lançamento do pacote de frota

Para excluir um pacote da frota, execute o seguinte comando:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Resolver problemas

Para encontrar métodos de diagnóstico e resolução de erros relacionados ao Cloud Build, consulte Solução de problemas de erros de build.

A seguir

• Consulte a página de referência dos campos FleetPackage.