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.

  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

  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 os 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.

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 da 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
    # Match all files and directories to generate variants
    variantsPattern: "*"
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
variantSelector:
  variantNameTemplate: "VARIANT_NAME"
# 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.

    • VARIANT_NAME: a variante a ser implantada nos clusters. O nome precisa corresponder a uma variante no seu repositório (o nome do arquivo sem extensão ou o nome do diretório). Por exemplo, se você tiver um arquivo chamado prod.yaml, defina este campo como prod. Para usar o comportamento padrão (por exemplo, para implantar a mesma configuração em todos os clusters de uma frota), defina esse campo como default e verifique se o repositório contém um arquivo chamado default.yaml.

      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 da frota definindo state: SUSPENDED. Quando um pacote de frota é suspenso, todos os rollouts em andamento continuam. Nenhum novo lançamento é criado ou programado até que você mude o estado de volta para ACTIVE.
  • Atualize os recursos do Kubernetes que o pacote de 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.

Inspecionar pacotes de recursos e versões

Quando você cria ou atualiza um pacote de frota com base no seu repositório Git, a API FleetPackages cria automaticamente recursos de pacote de recursos e lançamento. A inspeção desses recursos é útil para a solução de problemas, especialmente se você precisar verificar variantes geradas do seu repositório.

Para inspecionar pacotes de recursos e versões, use um ou mais dos seguintes comandos:

  • Confira informações detalhadas sobre um pacote de recursos específico:

    gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME

  • Liste todas as versões associadas a um pacote de recursos:

    gcloud container fleet packages resource-bundles releases list \
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

  • Confira informações detalhadas sobre uma versão específica, incluindo qual pacote de recursos ela usa. Esse comando é particularmente útil para depurar problemas relacionados a variantes porque permite inspecionar exatamente quais variantes foram incluídas em uma versão específica:

    gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

Substitua:

  • FLEET_PACKAGE_NAME: o nome do pacote da frota. O nome do pacote de recursos é prefixado automaticamente com flpkg-rb-.
  • RELEASE_NAME: o nome da versão na resposta ao comando list.

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 rollouts 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

    • Ao retomar um lançamento, um lançamento SUSPENDED volta ao estado IN_PROGRESS. As atualizações de pacote são implantadas nos clusters de destino conforme 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

Estratégias de implantação

É possível implantar recursos de diferentes maneiras, seja implantando em um subconjunto de clusters especificando rótulos ou usando correspondência de padrões de variantes para implantar recursos diferentes. Você pode combinar as duas estratégias para ter mais controle sobre quais recursos são implantados em diferentes clusters.

Implantar em um subconjunto de clusters

É possível implantar o mesmo recurso em um subconjunto de clusters usando rótulos e especificando o campo target.fleet.selector.matchLabels com seus rótulos (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".

Os pacotes de frota só são compatíveis com rótulos de associação à frota. Os rótulos de cluster do GKE não são compatíveis.

  1. (Opcional) Se você ainda não tiver os marcadores que quer usar, adicione-os seguindo 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.

  2. 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

  3. 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

É possível implantar configurações exclusivas em clusters diferentes (por exemplo, dev x prod) adicionando definições de variantes ao pacote da frota.

Para uma visão geral conceitual de como as variantes são geradas na estrutura do repositório, consulte Como as variantes são geradas.

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

  1. Crie ou atualize a especificação FleetPackage para incluir os campos variantsPattern e variantNameTemplate:

    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: um padrão glob para gerar variantes do repositório, como * (corresponde a todos os arquivos e diretórios) ou *.yaml (corresponde apenas a arquivos). Para mais informações sobre quais padrões são compatíveis, consulte Correspondência de variantsPattern.
    • VARIANT_NAME_TEMPLATE : uma string ou um modelo para selecionar uma variante para cada cluster. É possível usar variáveis de metadados, como ${membership.labels['env']} ou ${membership.location}.

  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