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 de frota 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 já precisam estar 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 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. Defina 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 repositórios do Cloud Build para criar uma conexão com um provedor compatível como GitHub ou GitLab. Ao usar um pacote de frota, você precisa configurar o Cloud Build apenas uma vez por repositório que quer sincronizar.

Analisar os requisitos do cluster

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

Preparar o ambiente

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

Instalar o Config Sync

É possível instalar o Config Sync com o Google Cloud console 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 Google Cloud console, a seleção de clusters individuais os registra automaticamente na frota.

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

    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 associação de frota escolhido ao registrar o cluster. Para encontrar o nome da associação, execute o comando gcloud container fleet memberships list.

Criar uma conta de serviço para o Cloud Build

Os pacotes de frota usam o Cloud Build para buscar os recursos do Kubernetes no seu repositório Git e implantá-los nos clusters. O Cloud Build exige uma conta de serviço que tenha as permissões 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 de 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 de 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 de 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 ao conectar o host do Git ao Cloud Build. É possível conferir todas as conexões do Cloud Build no seu projeto executando gcloud builds connections list ou abrindo a página Repositórios noconsole: 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 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 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 esse valor 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 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 esse 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 FleetPackage documentação de referência.

  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 de 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 compilação.

    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 compilação é 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 você adiciona um novo cluster à frota, os recursos do Kubernetes definidos no pacote de frota são implantados automaticamente no novo cluster.

Atualizar um pacote de frota

É possível atualizar um pacote de frota para mudar as configurações ou os recursos que o pacote de frota 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 lançamentos 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 Git diferente.

Para atualizar um pacote de frota, siga estas etapas:

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

  2. Atualize o pacote de 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

Ao criar ou atualizar um pacote de frota com base no repositório Git, a API FleetPackages cria automaticamente recursos de pacote de recursos e versão. A inspeção desses recursos é útil para a solução de problemas, especialmente se você precisar verificar as variantes geradas no 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 o pacote de recursos que 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 de 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 de frota

É possível monitorar o progresso das implantações de pacotes de frota e gerenciar lançamentos ativos. Quando um pacote de frota é alterado, um novo lançamento é criado automaticamente. Os comandos a seguir ajudam a receber informações detalhadas sobre os lançamentos. 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. A listagem de um lançamento permite conferir o status de todos os lançamentos vinculados a um pacote, incluindo erros que podem causar falha em um lançamento. Para listar os lançamentos e conferir 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 um lançamento, 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 receber o nome completo do lançamento no 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 lançamentos ativos executando os seguintes comandos:

    • A suspensão de um lançamento coloca um lançamento em andamento em um estado SUSPENDED. Todas as atualizações de pacote 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

    • A retomada de 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 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 pacote 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 maneiras diferentes, seja implantando em um subconjunto de clusters especificando rótulos ou usando a correspondência de padrões de variantes para implantar recursos diferentes. É possível combinar as duas estratégias para ter maior controle sobre quais recursos são implantados em clusters diferentes.

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 os rótulos (par de chave-valor). Por exemplo, se você definir matchLabels como country: "us", o serviço de pacote de frota vai implantar seus recursos apenas em clusters com o rótulo country que corresponda a "us".

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

  1. (Opcional) Se você ainda não tiver rótulos que quer usar, adicione-os seguindo estas etapas:

    1. Receba 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 à associação. 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 um caractere minúsculo e conter apenas hifens (-), sublinhados (_), caracteres minúsculos e números. Os valores precisam conter apenas hifens (-), sublinhados (_), caracteres minúsculos e números.

      Repita esse comando para cada associação 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 variante em clusters

É possível implantar configurações exclusivas em clusters diferentes (por exemplo, dev versus prod) adicionando definições de variante ao pacote de 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 variantsPattern correspondência.
    • VARIANT_NAME_TEMPLATE : uma string ou 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 clusters
  • O histórico de lançamento do pacote de frota

Para excluir um pacote de 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