Para informações sobre a versão, consulte as notas da versão conectada do Distributed Cloud.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Usar pacotes da frota no Distributed Cloud conectado

Esta página explica como usar pacotes de frota do Config Sync no ambiente do Google Distributed Cloud conectado. Os pacotes de frota são uma ferramenta que usa um repositório Git como a única fonte de verdade para a configuração do cluster.

Os pacotes de frota no Distributed Cloud conectado usam a mesma tecnologia e comandos subjacentes dos clusters padrão do Google Kubernetes Engine. A documentação do GKE explica como criar e gerenciar pacotes de frota na página Implantar pacotes de frota. Esta página explica como adaptar esse guia para o ambiente do Distributed Cloud conectado.

As seções a seguir explicam o que você precisa fazer de diferente para o Distributed Cloud conectado e quais etapas da documentação do GKE podem ser seguidas sem alterações.

Requisitos

O uso de pacotes de frota do Config Sync no Distributed Cloud conectado tem os seguintes requisitos:

Como o controlador de lançamento reside na nuvem, o repositório Git precisa ser acessível pela Internet pública. Servidores Git internos ou locais que não são expostos publicamente não são compatíveis.
O Distributed Cloud conectado só oferece suporte ao uso da federação de identidade da carga de trabalho da frota para autenticar com Google Cloud serviços. Outros métodos de autenticação do Config Sync, como chaves SSH ou cookies, não são compatíveis com a conexão entre os clusters e o repositório de pacote versionado. Para mais informações, consulte Autenticação de cluster de identidade da carga de trabalho.
Todos os clusters em uma frota precisam estar no mesmo projeto. O Distributed Cloud conectado não oferece suporte ao registro de clusters em vários projetos em um único projeto central para gerenciamento de frota.
Os manifestos do Kubernetes precisam obedecer às limitações de carga de trabalho do Distributed Cloud conectado. Os manifestos que violam essas restrições são bloqueados pelo controlador de admissão de cluster.
Os pacotes de frota exigem o Config Sync versão 1.16.0 ou mais recente.

Comportamento do sistema

Os pacotes de frota no Distributed Cloud conectado têm os seguintes comportamentos:

Os pacotes de frota transformam os manifestos do Kubernetes em imagens OCI versionadas. Essas imagens são armazenadas em um repositório gerenciado do Artifact Registry chamado fleet-packages, que é criado automaticamente no projeto. Os clusters extraem essas imagens diretamente do repositório para garantir a entrega consistente e confiável.
Os pacotes de frota herdam o comportamento de correção de desvio do Config Sync. As mudanças manuais feitas nos recursos de um cluster são substituídas automaticamente para corresponder aos pacotes OCI versionados.
Se um cluster do Distributed Cloud conectado entrar no modo de capacidade de sobrevivência, o agente do Config Sync continuará aplicando a última configuração sincronizada com sucesso localmente. No entanto, todos os novos lançamentos ou atualizações do pacote de frota serão pausados até que a conectividade da nuvem seja restaurada.
Os pacotes de frota herdam o comportamento de remoção automática de recursos do Config Sync. Ao criar uma nova tag no repositório Git e atualizar a configuração do pacote de frota com a nova tag para iniciar uma sincronização, o agente do Config Sync exclui o recurso correspondente do cluster se você remover um manifesto do repositório Git.
Se vários pacotes de frota gerenciarem o mesmo recurso, ocorrerá um conflito de propriedade. Se você tentar excluir um pacote de frota enquanto ele estiver em um conflito de propriedade, a exclusão poderá ser interrompida. Para resolver esse problema, modifique um dos pacotes de frota concorrentes para remover o recurso conflitante antes de tentar excluir o pacote.

Pré-requisitos do Distributed Cloud conectado

Antes de seguir as etapas em Implantar pacotes de frota, verifique se o ambiente do Distributed Cloud conectado e as permissões do usuário estão configurados corretamente.

Rede e segurança

O ambiente de rede precisa atender aos seguintes requisitos:

VPC Service Controls. Se o projeto estiver protegido por um perímetro de serviço VPC, verifique se os agentes de serviço do Cloud Build e do Config Delivery, por exemplo, service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com, estão autorizados a cruzar o perímetro e extrair imagens do Artifact Registry. Para mais informações, consulte Configurar a integração do VPC Service Controls.
Acesso de saída. Os clusters do Distributed Cloud conectado precisam ter acesso de saída a us-central1-docker.pkg.dev. Os pacotes de frota armazenam os pacotes de manifesto como imagens OCI no Artifact Registry. Os clusters precisam extrair essas imagens diretamente do Artifact Registry.

Configuração do repositório

O repositório do Artifact Registry que contém os pacotes de manifesto precisa estar no mesmo projeto que o pacote de frota e estar localizado em us-central1.

Permissões necessárias

Para concluir as etapas no ambiente do Distributed Cloud conectado, você precisa ter os seguintes papéis do IAM no projeto:

Administrador do Config Delivery (roles/configdelivery.admin): necessário para criar e gerenciar pacotes de frota e lançamentos
Administrador do Developer Connect (roles/developerconnect.admin): necessário para criar e gerenciar conexões de repositório
Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin): necessário para conceder os papéis necessários à conta de serviço

Para mais informações sobre como conceder papéis, consulte Conceder, alterar e revogar o acesso a recursos.

APIs necessárias

É necessário ativar as APIs para conexões de repositório e comunicação segura com clusters do Distributed Cloud conectado. Para ativar as APIs necessárias, execute o seguinte gcloud services enable comando:

gcloud services enable anthosconfigmanagement.googleapis.com \
    configdelivery.googleapis.com \
    cloudbuild.googleapis.com \
    connectgateway.googleapis.com \
    developerconnect.googleapis.com \
    artifactregistry.googleapis.com

Essas APIs são necessárias para os seguintes componentes:

anthosconfigmanagement.googleapis.com: gerencia o agente do Config Sync nos clusters
configdelivery.googleapis.com: coordena o lançamento de recursos do Kubernetes na frota de clusters
cloudbuild.googleapis.com: busca os manifestos do Kubernetes no Git e os empacota em pacotes versionados
connectgateway.googleapis.com: fornece uma conexão segura entre o serviço Config Delivery e os clusters do Distributed Cloud conectado
developerconnect.googleapis.com: permite conexões seguras com o host do repositório Git externo
artifactregistry.googleapis.com: armazena os pacotes versionados como imagens OCI no projeto

Permissões RBAC de cluster necessárias

É necessário conceder as permissões RBAC descritas nesta seção ao agente de serviço do Config Delivery (P4SA) no cluster para que ele possa gerenciar objetos do Config Sync.

Para conceder essas permissões, aplique o seguinte manifesto ao cluster:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: fleet-packages-impersonator
rules:
- apiGroups:
  - ""
  resourceNames:
  - P4SA_EMAIL
  resources:
  - users
  verbs:
  - impersonate
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: fleet-packages-impersonator-binding
roleRef:
  kind: ClusterRole
  name: fleet-packages-impersonator
  apiGroup: rbac.authorization.k8s.io
subjects:
- kind: ServiceAccount
  name: connect-agent-sa
  namespace: gke-connect
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: fleetpackages-configsync-admin
rules:
- apiGroups:
  - "configsync.gke.io"
  resources:
  - rootsyncs
  - reposyncs
  verbs:
  - "*"
- apiGroups:
  - "kpt.dev"
  resources:
  - resourcegroups
  verbs:
  - "*"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: fleet-packages-configsync-admin-binding
subjects:
- kind: User
  name: P4SA_EMAIL
roleRef:
  kind: ClusterRole
  name: fleetpackages-configsync-admin
  apiGroup: rbac.authorization.k8s.io

Substitua P4SA_EMAIL pelo e-mail do agente de serviço do Config Delivery, que normalmente segue este formato: service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com.

Configurações de ambiente padrão

A API Config Delivery para pacotes de frota só é compatível com us-central1. Para garantir que os comandos sejam roteados corretamente, use o gcloud config set comando para definir seu projeto e local padrão:

Defina seu projeto padrão:
```
gcloud config set project PROJECT_ID
```
Substitua PROJECT_ID pelo Google Cloud ID do projeto.
Defina o local padrão para pacotes de frota. Todas as conexões de repositório do Cloud Build usadas com pacotes de frota precisam estar na região us-central1.
```
gcloud config set config_delivery/location us-central1
```

Diferenças de procedimento

Use a tabela a seguir para entender como aplicar as etapas em Implantar pacotes de frota ao ambiente do Distributed Cloud conectado.

Etapa padrão	Ajuste do Distributed Cloud conectado
Registrar clusters em uma frota	Pule esta etapa. Os clusters do Distributed Cloud conectado são registrados automaticamente em uma frota no projeto quando são criados.
Instalar o Config Sync	Siga as etapas padrão, mas recomendamos usar o Instalar em toda a frota (padrão da frota) método. Configure este método nas configurações do Hub ou da Frota no Google Cloud console. Essa implementação garante que todos os nós do Distributed Cloud conectado atuais ou futuros na sua zona recebam automaticamente o agente do Config Sync. Para o tipo de membro de autenticação, selecione Identidade da carga de trabalho. A conta de serviço usada para a Identidade da carga de trabalho precisa ter o papel `roles/artifactregistry.reader` no projeto para que o agente do Config Sync possa extrair pacotes de manifesto do repositório gerenciado `fleet-packages`.
Configurar o RBAC do cluster	Para o Distributed Cloud conectado, é necessário conceder explicitamente permissões RBAC ao agente de serviço do Config Delivery (P4SA) nos clusters. Consulte RBAC de cluster necessário para mais detalhes.
Criar uma conta de serviço	Siga as instruções para criar uma conta de serviço para Cloud Build e conceder as permissões necessárias. A conta de serviço precisa estar no mesmo projeto que o pacote de frota. Recomendamos que você use os seguintes comandos: Crie a conta de serviço executando o `gcloud iam service-accounts create` comando: gcloud iam service-accounts create "`SERVICE_ACCOUNT_NAME`" Substitua `SERVICE_ACCOUNT_NAME` por um nome para a conta de serviço. Adicione os papéis obrigatórios do Identity and Access Management executando o `gcloud projects add-iam-policy-binding` comando para cada um dos seguintes papéis. Para mais informações sobre o IAM, consulte a visão geral do IAM. `roles/configdelivery.resourceBundlePublisher`: permite que a conta de serviço crie e gerencie pacotes e lançamentos de recursos `roles/cloudbuild.connectionUser`: permite que a conta de serviço use a conexão do repositório do Cloud Build `roles/logging.logWriter`: permite que a conta de serviço grave registros de build `roles/artifactregistry.writer`: permite que a conta de serviço envie pacotes versionados para o Artifact Registry `roles/developerconnect.connectionUser`: permite que a conta de serviço use a conexão do Developer Connect A conta de serviço também precisa de permissão para ler o repositório Git conectado no provedor do Git. Para informações sobre como autorizar a conexão, consulte Conectar-se a um repositório.
Identificar o nome da assinatura	Quando um comando solicitar um `MEMBERSHIP_NAME`, use o nome do cluster do Distributed Cloud conectado. Para encontrar o nome do cluster, execute o `gcloud container fleet memberships list` comando.
Identificar um cluster	Antes de segmentar um cluster com um pacote de frota, se as cargas de trabalho exigirem configuração de rede no nível do host, como HugePages ou SR-IOV, aplique e verifique os `NodeSystemConfigUpdate` recursos em cada nó do cluster.
Identificar tags do Git	O controlador de lançamento exige que as tags do Git estejam em um formato de versão semântica completa (`major.minor.patch`). Por exemplo, `v1.0.0` é válido, enquanto `v1` não é.
Segmentar clusters específicos	Embora os clusters sejam registrados automaticamente, é necessário adicionar manualmente rótulos às assinaturas de cluster se você quiser segmentar subconjuntos de clusters usando seletores de rótulos.
Estratégias de implantação	Use rótulos e variantes para segmentar clusters específicos. Para o Distributed Cloud conectado, as variáveis de metadados de assinatura, como projeto e local, usadas nos modelos de variante se referem aos recursos do lado da nuvem associados ao cluster do Distributed Cloud conectado. Os seguintes metadados de assinatura específicos do Distributed Cloud estão disponíveis para uso em modelos de variante: `cluster_name`: o nome do cluster do Distributed Cloud conectado `location`: a Google Cloud região associada com o cluster `project`: o ID do projeto em que o cluster está registrado `labels`: todos os rótulos aplicados à assinatura do cluster

Procedimentos compartilhados

Para as seguintes tarefas operacionais, a sintaxe do comando e o comportamento do serviço são os mesmos para o Distributed Cloud conectado e o GKE padrão. Ao seguir estas instruções, use as configurações e os valores definidos na tabela na seção Diferenças de procedimento deste documento.

Criar um pacote de frota: Defina o recurso FleetPackage para buscar e implantar a configuração.
Atualizar um pacote de frota: modifique o pacote para lançar mudanças ou atualizar configurações.
Gerenciar lançamentos de pacotes de frota: suspenda, retome ou aborte lançamentos ativos.
Inspecionar pacotes e lançamentos de recursos: Depure a geração e o controle de versões de variantes. Os pacotes de recursos são contêineres para suas configurações, e os lançamentos são instâncias versionadas desses pacotes. Para verificar a entrega bem-sucedida ao hardware do Distributed Cloud conectado, use o gcloud container fleet memberships get-credentials comando para acessar o cluster, e, em seguida, use kubectl para inspecionar o status RootSync no cluster.
Excluir um pacote de frota: Remova um pacote de frota e os recursos gerenciados. Para garantir uma remoção limpa, verifique se os objetos RootSync gerenciados associados ao pacote de frota foram removidos dos clusters.

Monitoramento e solução de problemas

Para monitorar as implantações com mais eficiência, use a flag --format com o comando gcloud para receber mensagens de status detalhadas durante um lançamento.

Por exemplo, execute o seguinte gcloud container fleet packages rollouts describe comando para conferir uma mensagem de status detalhada para cada cluster na frota:

gcloud container fleet packages rollouts describe ROLLOUT_NAME \
    --fleet-package=FLEET_PACKAGE_NAME \
    --format=json

Substitua os seguintes valores:

ROLLOUT_NAME: o nome do lançamento.
FLEET_PACKAGE_NAME: o nome do pacote de frota.

Se um build falhar ou ficar preso, você poderá encontrar um link para os registros de streaming do job do Cloud Build na saída do gcloud container fleet packages list comando. Se um lançamento permanecer no estado PENDING ou STALLED, verifique a conectividade do hardware do Distributed Cloud conectado, conforme descrito em Solução de problemas do Distributed Cloud conectado.

Para mais informações sobre como diagnosticar erros relacionados ao Cloud Build, consulte Solução de problemas de build.

Verificar o status da sincronização no cluster

Para verificar se o cluster está sincronizando com o pacote de frota, examine o recurso RootSync no cluster. O nome do objeto RootSync no cluster é idêntico ao FLEET_PACKAGE_NAME escolhido para o pacote.

Para verificar o status, execute o comando a seguir.

kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system

Uma sincronização bem-sucedida mostra um status SYNCED. Se você vir um status Error, para mais detalhes, execute o seguinte comando:

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

Para mais informações, consulte Monitorar objetos RootSync e RepoSync na documentação do GKE.

Para receber ajuda na decodificação de códigos de erro específicos na saída, consulte a referência de erros do Config Sync.

Usar pacotes da frota no Distributed Cloud conectado Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.