Nesta página, explicamos como usar pacotes de frota do Config Sync no seu ambiente conectado do Google Distributed Cloud. Os pacotes da 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 Google Distributed Cloud Connected usam a mesma tecnologia e os mesmos comandos dos clusters padrão do Google Kubernetes Engine. A documentação do GKE explica como criar e gerenciar pacotes da frota na página Implantar pacotes da frota. Nesta página, explicamos como adaptar esse guia ao seu ambiente conectado do Distributed Cloud.
As seções a seguir explicam o que você precisa fazer de diferente para o Distributed Cloud Connected 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 Connected tem os seguintes requisitos:
- Como o controlador de lançamento reside na nuvem, seu repositório Git precisa estar acessível pela Internet pública. Servidores Git internos ou locais que não estão expostos publicamente não são compatíveis.
- O Distributed Cloud Connected só aceita o uso da federação de identidade da carga de trabalho da frota para autenticar com serviços do Google Cloud . 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 seus clusters e o repositório de pacotes com controle de versões. Para mais informações, consulte Autenticação de cluster da Identidade da carga de trabalho.
- Todos os clusters em uma frota precisam estar no mesmo projeto. O Distributed Cloud Connected não oferece suporte ao registro de clusters em vários projetos em um único projeto central para gerenciamento de frotas.
- Seus manifestos do Kubernetes precisam obedecer às limitações de carga de trabalho conectada do Distributed Cloud. Manifestos que violam essas restrições são bloqueados pelo controlador de admissão do cluster.
- Os pacotes da frota exigem o Config Sync versão 1.16.0 ou mais recente.
Comportamento do sistema
Os pacotes da frota no Distributed Cloud Connected têm os seguintes comportamentos:
- Os pacotes de frota transformam seus 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 seu projeto. Seus clusters extraem essas imagens diretamente do repositório para garantir uma 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 conectado do Distributed Cloud entrar no modo de capacidade de sobrevivência, o agente do Config Sync vai continuar aplicando a última configuração sincronizada com sucesso localmente. No entanto, novos lançamentos ou atualizações do pacote da frota são pausados até que a conectividade com a nuvem seja restaurada.
- Os pacotes de frota herdam o comportamento de remoção automática de recursos do Config Sync. Quando você cria uma nova tag no repositório Git e atualiza a configuração do pacote da 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 da frota gerenciarem o mesmo recurso, vai 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 em conflito antes de tentar excluir o pacote.
Pré-requisitos do Distributed Cloud conectado
Antes de seguir as etapas em Implantar pacotes da frota, verifique se o ambiente conectado do Distributed Cloud e as permissões de usuário estão configurados corretamente.
Rede e segurança
Seu ambiente de rede precisa atender aos seguintes requisitos:
- VPC Service Controls. Se o projeto estiver protegido por um perímetro de serviço da 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 conectados do Distributed Cloud precisam ter
acesso de saída a
us-central1-docker.pkg.dev. Os pacotes da frota armazenam seus pacotes de manifestos como imagens OCI no Artifact Registry. Os clusters precisam conseguir 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 do pacote da frota e estar localizado em us-central1.
Permissões necessárias
Para concluir as etapas no ambiente conectado do Distributed Cloud, 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 e implantações de frota. - 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 conectados do Distributed Cloud. Para ativar as APIs necessárias, execute o seguinte comando
gcloud services enable:
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 seus clusters.configdelivery.googleapis.com: coordena o lançamento de recursos do Kubernetes em toda a frota de clusterscloudbuild.googleapis.com: busca seus 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 seus clusters conectados do Distributed Cloud.developerconnect.googleapis.com: permite conexões seguras com seu host de repositório Git externo.artifactregistry.googleapis.com: armazena os pacotes com versão como imagens OCI no seu projeto.
Configurações de ambiente padrão
A API Config Delivery para pacotes de frota só é compatível com
us-central1. Para garantir que seus comandos sejam encaminhados corretamente, use o
comando gcloud config set para definir o
projeto e o local padrão:
Defina seu projeto padrão:
gcloud config set project PROJECT_ID
Substitua
PROJECT_IDpelo Google Cloud ID do projeto.Defina o local padrão para pacotes da 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 no seu ambiente conectado do Distributed Cloud.
| Etapa padrão | Ajuste do Distributed Cloud conectado |
|---|---|
| Registrar clusters em uma frota | Ignorar esta etapa. Os clusters conectados do Distributed Cloud são registrados automaticamente em uma frota no seu projeto quando são criados. |
| Instale o Config Sync | Siga as etapas padrão, mas recomendamos usar o método
Instalar em toda a frota (padrão da frota). Configure esse método nas configurações de Hub ou Frota no console do Google Cloud .
Essa implementação garante que todos os nós conectados do Distributed Cloud 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 manifestos do
repositório fleet-packages gerenciado. |
| Criar uma conta de serviço | Siga as instruções para criar uma conta de serviço para o
Cloud Build e conceder as permissões necessárias. A conta de serviço precisa estar no mesmo projeto do pacote da frota. Recomendamos
que você use os seguintes comandos:
|
| Identificar o nome da assinatura | Quando um comando pedir um MEMBERSHIP_NAME, use o nome do cluster conectado do Distributed Cloud. Para encontrar o nome do cluster, execute o comando
gcloud container fleet memberships list. |
| Identificar um cluster | Antes de segmentar um cluster com um pacote da 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 recursos
NodeSystemConfigUpdate
em todos os nós 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, mas v1 não é. |
| Segmentar clusters específicos | Embora os clusters sejam registrados automaticamente, é necessário adicionar rótulos manualmente às associações de cluster se você quiser segmentar subconjuntos de clusters usando seletores de rótulo. |
| Estratégias de implantação | Use rótulos e variantes para segmentar clusters específicos. Para o Distributed Cloud Connected, as variáveis de metadados de associação, como projeto e local, usadas nos modelos de variantes se referem aos recursos do lado da nuvem associados ao cluster conectado do Distributed Cloud. Os seguintes metadados de associação específicos do Distributed Cloud estão disponíveis para uso em modelos de variantes:
|
Procedimentos compartilhados
Para as seguintes tarefas operacionais, a sintaxe de comando e o comportamento do serviço são os mesmos para o GKE conectado e padrão do Distributed Cloud. Ao seguir estas instruções, use as configurações e os valores definidos na tabela da seção Diferenças de procedimento deste documento.
- Crie um pacote de frota:
defina o recurso
FleetPackagepara buscar e implantar sua configuração. - Atualizar um pacote de frota: modifique o pacote para lançar mudanças ou atualizar configurações.
- Gerenciar implantações de pacotes da frota: suspender, retomar ou cancelar implantações ativas.
- Inspecionar pacotes de recursos e versões:
depurar a geração e o controle de versões de variantes. Os pacotes de recursos são contêineres para suas configurações, e as versões são instâncias versionadas desses pacotes. Para verificar se a entrega foi feita com sucesso no hardware do Distributed Cloud Connected, use o comando
gcloud container fleet memberships get-credentialspara acessar o cluster e, em seguida, usekubectlpara inspecionar o status doRootSyncno cluster. - Excluir um pacote da frota:
remove um pacote da frota e os recursos gerenciados dele. Para garantir uma remoção
limpa, verifique se os objetos
RootSyncgerenciados associados ao pacote da frota foram removidos dos clusters.
Monitoramento e solução de problemas
Para monitorar 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 comando
gcloud container fleet packages rollouts describe
a seguir para conferir uma mensagem de status detalhada de cada cluster na sua 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 da 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 comando
gcloud container fleet packages list. Se um lançamento permanecer no estado PENDING ou STALLED, verifique a conectividade do hardware conectado do Distributed Cloud, conforme descrito em Solução de problemas do Distributed Cloud Connected.
Para mais informações sobre como diagnosticar erros relacionados ao Cloud Build, consulte Solução de problemas de erros de build.
Verificar o status da sincronização no cluster
Para verificar se o cluster está sincronizando com o pacote da 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ê encontrar 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 ajuda a decodificar códigos de erro específicos na saída, consulte a referência de erros do Config Sync.