Implemente pacotes de frotas

Esta página explica como usar pacotes de frotas do Config Sync para implementar recursos do Kubernetes em clusters registados numa frota. Depois de criar e implementar um pacote de frota, quando adiciona um novo cluster à sua frota, o pacote de frota implementa automaticamente os ficheiros de configuração do Kubernetes no repositório Git para o novo cluster.

Um FleetPackage é uma API declarativa para implementar manifestos brutos do Kubernetes numa frota de clusters. Todos os recursos do Kubernetes que quer implementar com um pacote de frota têm de estar já hidratados (WET).

Antes de começar

  1. Crie ou certifique-se de que tem acesso a um repositório Git com os recursos do Kubernetes que quer implementar numa frota.

  2. Instale e inicialize a CLI Google Cloud, que fornece os comandos gcloud e nomos. Se usar o Cloud Shell, a CLI do Google Cloud está pré-instalada. Se instalou anteriormente a Google Cloud CLI, obtenha 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. Predefina uma localização:

    gcloud config set config_delivery/location us-central1

  5. Defina um projeto predefinido:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto do projeto anfitrião da frota.

  6. Certifique-se de que os seus clusters estão registados numa frota.

  7. Use repositórios do Cloud Build para criar uma ligação a um fornecedor suportado como o GitHub ou o GitLab. Quando usa um pacote de frota, só precisa de configurar o Cloud Build uma vez por repositório que quer sincronizar.

Reveja os requisitos do cluster

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

Prepare o seu ambiente

Para preparar o seu ambiente para pacotes de frotas do Config Sync, conceda as funções de IAM necessárias ao utilizador que regista o cluster.

Instale o Config Sync

Pode instalar o Config Sync com a Google Cloud consola ou a CLI do Google Cloud.

Consola

Para instalar o Config Sync, todos os clusters têm de estar registados numa frota. Quando instala o Config Sync na Google Cloud consola, a seleção de clusters individuais regista automaticamente esses clusters na sua frota.

  1. Na Google Cloud consola, aceda à página Configuração na secção Funcionalidades.

    Aceda à configuração

  2. Clique em Instalar Config Sync.

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

  4. Clique em Instalar Config Sync. No separador Definições, após alguns minutos, deve ver Ativado na coluna Estado para os clusters na sua frota.

gcloud

  1. Ative a funcionalidade de frota ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Para ativar a sincronização de configuração, crie um ficheiro denominado apply-spec.yaml com o seguinte conteúdo:

    applySpecVersion: 1
spec:
  configSync:
    enabled: true

  3. Aplique o ficheiro apply-spec.yaml:

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

    Substitua MEMBERSHIP_NAME pelo nome da subscrição da frota que escolheu quando registou o cluster. Para encontrar o nome da subscrição, execute o comando gcloud container fleet memberships list.

Crie uma conta de serviço para o Cloud Build

Os pacotes da frota usam o Cloud Build para obter os recursos do Kubernetes do seu repositório Git e implementam-nos nos seus clusters. O Cloud Build requer uma conta de serviço com as autorizações para executar esta tarefa. Para criar a conta de serviço e conceder as autorizações necessárias, conclua os passos seguintes:

  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 tem de ser um ID alfanumérico entre 6 e 30 carateres, por exemplo, my-service-account. Depois de criar uma conta de serviço, não pode alterar o respetivo nome.

  2. Adicione uma vinculação de política do IAM para a função de publicador 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 lhe for pedido, selecione None como condição para a política.

  3. Adicione uma associação de política de IAM para a função Logs Writer:

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

    Se lhe for pedido, selecione None como condição para a política.

  4. Adicione uma associação de política IAM para a função ArtifactRegistry Writer:

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

    Se lhe for pedido, selecione None como condição para a política.

Crie um pacote de frota

Para criar um pacote de frota, define uma especificação FleetPackage que aponta para o repositório com os seus recursos do Kubernetes que associou ao Cloud Build. Em seguida, aplica o FleetPackage que obtém os recursos do Git e os implementa em toda a frota.

  1. Crie um ficheiro denominado fleetpackage-spec.yaml com o seguinte conteúdo:

    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 o seguinte:

    • CONNECTION_NAME: o nome que escolheu quando associou o seu anfitrião Git ao Cloud Build. Pode ver todas as associações do Cloud Build no seu projeto executando o comando gcloud builds connections list ou abrindo a página Repositórios na Google Cloud consola:

      Abra a página Repositórios

    • REPOSITORY_NAME: o nome do seu repositório. Este valor tem de ser idêntico ao valor introduzido quando configurou a ligação do Cloud Build.

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

    • CONFIG_FILE_PATH: o caminho para os seus recursos do Kubernetes no repositório. Se os seus ficheiros estiverem na raiz do repositório, pode omitir este campo.

    • MAX_CLUSTERS: o número máximo de clusters para implementar recursos do Kubernetes de uma só vez. Por exemplo, se definir este valor como 1, os pacotes de recursos são implementados num cluster de cada vez.

      Para ver uma lista completa de todos os campos que pode configurar, 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 a implementação do pacote da sua frota.

  3. Verifique se o pacote de frota foi criado:

    gcloud container fleet packages list

    O resultado apresenta o estado do acionador de compilação. Após alguns segundos, o campo MESSAGE é atualizado com um resultado semelhante ao seguinte:

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

    Pode clicar no link fornecido para ver os registos de streaming da tarefa do Cloud Build. O Cloud Build pode demorar alguns minutos a processar o acionador de compilação.

    Se o acionador de compilação for bem-sucedido, o pacote da frota começa a implementar os recursos do Kubernetes na sua frota.

  4. Quando o acionador de compilação é concluído com êxito, o resultado de 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 frotas começa a implementar os recursos do Kubernetes na sua frota.

Agora que implementou um pacote de frota, quando adiciona um novo cluster à sua frota, os recursos do Kubernetes definidos no pacote de frota são implementados automaticamente no novo cluster.

Atualize um pacote de frota

Pode atualizar um pacote de frota para alterar as definições ou os recursos que o pacote de frota implementa, como nos seguintes exemplos:

  • Altere a estratégia de implementação alterando o valor do campo maxConcurrent.
  • Pause temporariamente um pacote de frota definindo state: SUSPENDED. Quando um pacote de frota é suspenso, as implementações em curso continuam. Não são criadas nem agendadas novas implementações até alterar o estado novamente para ACTIVE.
  • Atualize os recursos do Kubernetes que o pacote da frota implementa atualizando o campo tag para extrair de uma etiqueta Git diferente.

Para atualizar um pacote de frota, conclua os seguintes passos:

  1. Atualize a sua FleetPackageespecificação com as alterações.

  2. Atualize o pacote de frota:

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

    Pode demorar alguns minutos até que a alteração seja detetada e comece a ser implementada nos seus clusters.

Faça a gestão das implementações de pacotes de frotas

Pode monitorizar o progresso das implementações de pacotes de frotas e gerir implementações ativas. Quando um pacote de frota é alterado, é criada automaticamente uma nova implementação. Os seguintes comandos ajudam a obter informações detalhadas sobre as implementações. Por exemplo, se precisar de depurar um problema de implementação, pode examinar os detalhes da implementação e pausar ou cancelar uma implementação, se necessário.

  1. A listagem de uma implementação permite-lhe ver o estado de todas as implementações associadas a um pacote, incluindo erros que possam fazer com que uma implementação falhe. Para apresentar uma lista de implementações e ver o respetivo estado, execute o seguinte comando:

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

    O resultado é semelhante ao seguinte:

    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 uma implementação fornece informações detalhadas sobre uma implementação específica, incluindo o estado de cada cluster segmentado e quaisquer 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 da implementação. Pode obter o nome de implementação completo a partir do comando list no passo anterior.

    O resultado é semelhante ao seguinte:

    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. Pode gerir implementações ativas executando os seguintes comandos:

    • A suspensão de uma implementação coloca uma implementação em curso num estado SUSPENDED. As atualizações de pacotes em curso continuam e não são agendadas mais atualizações de pacotes. Para suspender uma implementação, execute o seguinte comando:

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

    • A retoma de uma implementação altera uma implementação SUSPENDED para um estado IN_PROGRESS. As atualizações de pacotes são implementadas nos clusters de destino conforme planeado. Para retomar uma implementação, execute o seguinte comando:

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

    • O cancelamento de uma implementação em curso termina imediatamente a implementação, colocando-a no estado ABORTED. Todas as atualizações de pacotes pendentes planeadas como parte da implementação são canceladas. Para cancelar uma implementação, execute o seguinte comando:

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

Use etiquetas para implementar em diferentes clusters

As etiquetas são pares de chave-valor que anexa a objetos. Os pacotes de frotas só suportam etiquetas de associação de frotas. As etiquetas de cluster do GKE não são suportadas.

Pode usar etiquetas para implementar um pacote de frota num subconjunto de clusters na sua frota.

Adicione etiquetas de apoiantes

Para adicionar uma etiqueta de subscrição, conclua os seguintes passos:

  1. Obtenha uma lista de subscrições na frota:

    gcloud container fleet memberships list

  2. Adicione uma etiqueta à subscrição:

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

    Substitua o seguinte:

    • MEMBERSHIP_NAME: o nome do cluster registado na frota.
    • KEY e VALUE: a etiqueta a adicionar à subscrição. Se existir uma etiqueta, o respetivo valor é modificado. Caso contrário, é criada uma nova etiqueta. As chaves têm de começar com um caráter em minúsculas e conter apenas hífenes (-), sublinhados (_), carateres em minúsculas e números. Os valores têm de conter apenas hífenes (-), sublinhados (_), carateres em minúsculas e números.

    Repita este comando para cada subscrição à qual quer adicionar uma etiqueta.

Implemente num subconjunto de clusters

Pode implementar num subconjunto de clusters especificando o campo target.fleet.selector.matchLabels com o seu par de chave-valor. Por exemplo, se definir matchLabels como country: "us", o serviço de pacote de frota implementa os seus recursos apenas em clusters com a etiqueta country que corresponda a "us".

Para implementar um pacote de frotas num subconjunto de clusters, conclua os seguintes passos:

  1. Crie ou atualize a sua especificação FleetPackage com o seletor de etiquetas:

    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:

    Crie um pacote de frota

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

    Atualize um pacote de frota

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

Implemente recursos variantes em clusters

As variantes são versões diferentes de um recurso. Estes recursos podem ter valores diferentes consoante a localização, o projeto ou o nome do cluster. Pode implementar recursos variantes em clusters diferentes especificando os campos variantsPattern e variantNameTemplate.

Pode usar etiquetas de registo de membro ou outros metadados de registo de membro, como localização, projeto ou nome, para fazer corresponder variantes.

Para implementar um pacote de frota com variantes, conclua os seguintes passos:

  1. Crie ou atualize a sua 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 o seguinte:

    • 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 associação ao cluster, como localização, projeto, nome ou etiqueta, para determinar o nome da variante para um cluster de destino. Para ver mais exemplos, consulte a FleetPackage documentação de referência.

  2. Crie ou atualize o pacote de frota:

    Crie um pacote de frota

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

    Atualize um pacote de frota

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

Elimine um pacote de frota

A eliminação de um pacote de frota também elimina os seguintes recursos:

  • Os recursos do Kubernetes implementados nos seus clusters
  • O histórico de implementações do pacote de frota

Para eliminar 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 com o Cloud Build, consulte o artigo Resolução de problemas de erros de compilação.

O que se segue?