Introdução à solução de problemas

Em caso de dificuldades com a Config Sync, esta página apresenta algumas ferramentas e procedimentos comuns que podem ajudar a identificar e resolver problemas.

Fazer upgrade para uma versão aceita

Considere fazer upgrade da Config Sync para uma versão aceita. A atualização geralmente resolve problemas comuns e oferece acesso às funcionalidades mais recentes.

Use a ferramenta de linha de comando nomos

A ferramenta de linha de comando nomos fornece insights essenciais sobre a configuração da Config Sync. Os comandos descritos nas seções a seguir são particularmente úteis para determinar a origem do problema ou quando é necessário trabalhar com o Cloud Customer Care.

Ver o status do Config Sync

O comando nomos status exibe dados agregados e erros para ajudar você a entender o que está acontecendo com a instalação da Config Sync. As informações a seguir estão disponíveis com nomos status:

  • Status da instalação por cluster
  • Erros de sincronização (na leitura do Git e na reconciliação das alterações)

Criar um relatório do bug

Em caso de problemas com a Config Sync que exijam a ajuda do Cloud Customer Care, forneça informações importantes de depuração usando o comando nomos bugreport.

Esse comando gera um arquivo zip com carimbo de data / hora com informações sobre o cluster do Kubernetes definido no contexto kubectl. O arquivo contém registros dos pods do Config Sync. Ele não contém informações dos recursos sincronizados com a Config Sync.

Acessar o painel de visão geral

O painel da Config Sync apresenta uma visão geral do status dos pacotes que a Config Sync gerencia e dos recursos nesses pacotes. A análise desse painel pode oferecer uma visão geral rápida do status da instalação da Config Sync e descobrir pacotes com problemas.

  • Para acessar o painel, no console Google Cloud , acesse a página Configuração na seção Recursos:

    Acessar a configuração

Usar o monitoramento e a análise de registros

Ao monitorar a Config Sync e analisar os registros dela, é possível determinar a origem dos bugs e entender melhor comportamentos inesperados.

Entender as métricas da Config Sync

Use as métricas da Config Sync para conferir a integridade da Config Sync.

Monitorar objetos RootSync e RepoSync

Ao instalar o Config Sync usando o console Google Cloud ou a Google Cloud CLI, a ferramenta cria automaticamente um objeto RootSync para você. Ao configurar a sincronização de vários repositórios, você cria objetos RepoSync que contêm informações de configuração sobre os repositórios de namespace.

A análise desses objetos pode revelar informações valiosas sobre o estado da Config Sync. Para saber mais, consulte Monitorar objetos RootSync e RepoSync.

Usar indicadores de nível de serviço (SLIs)

Para receber notificações quando o Config Sync não estiver funcionando como esperado, use os SLIs do Config Sync.

Registros da consulta

Use a Análise de registros para recuperar, exibir e analisar dados de registro da Config Sync. Esses registros podem conter dados históricos valiosos que não são capturados por nomos bugreport quando os pods do operador ou do reconciliador são reiniciados. Para exemplos de consultas que podem ajudar a diagnosticar o problema, consulte Consultar os registros da Config Sync.

Analisar recursos com a ferramenta de linha de comando kubectl

O Config Sync é composto de vários recursos personalizados que podem ser consultados usando comandos kubectl. Esses comandos ajudam você a entender o status de cada um dos objetos da Config Sync.

Você precisa conhecer as seguintes informações sobre os recursos do Kubernetes que o Config Sync gerencia:

  • config-management-system é o namespace usado para executar todos os principais componentes do sistema da Config Sync.
  • configmanagement.gke.io e configsync.gke.io são os grupos de API usados para todos os recursos personalizados.

Exemplos

As seções a seguir mostram como usar comandos kubectl para analisar a Config Sync.

Listar recursos personalizados

  • Veja uma lista completa dos recursos personalizados executando o seguinte comando:

    kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"

  • Execute o seguinte comando para consumir recursos personalizados individuais:

    kubectl get RESOURCE -o yaml.

    Substitua RESOURCE pelo nome do recurso que você quer consultar.

    Por exemplo, a saída do comando a seguir permite verificar o status de um objeto RootSync:

    kubectl get rootsync -n config-management-system -o yaml

Verificar a anotação de token de um objeto

É possível saber quando um objeto do Kubernetes gerenciado foi atualizado pela última vez pelo Config Sync. Cada objeto gerenciado recebe a anotação do hash da confirmação do Git com relação à última modificação e do caminho para a configuração que a continha.

Por exemplo, para receber a anotação de um ClusterRoleBinding chamado namespace-readers, execute este comando:

kubectl get clusterrolebinding namespace-readers

O resultado será assim:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/source-path: cluster/namespace-reader-clusterrolebinding.yaml
    configmanagement.gke.io/token: bbb6a1e2f3db692b17201da028daff0d38797771
  name: namespace-readers
...

Para mais informações, consulte rótulos e anotações.

Acelere o diagnóstico com o Gemini Cloud Assist

Às vezes, a causa do problema não fica imediatamente óbvia, mesmo depois de usar as ferramentas discutidas nas seções anteriores. Investigar casos complexos pode levar tempo e exige muita experiência. Para cenários como esse, o Gemini Cloud Assist pode ajudar. Ele pode detectar automaticamente padrões ocultos, identificar anomalias e fornecer resumos para ajudar você a identificar rapidamente uma causa provável.

Acessar o Gemini Cloud Assist

Para acessar o Gemini Cloud Assist, siga estas etapas:

  1. No console do Google Cloud , acesse qualquer página.

  2. Na barra de ferramentas do console Google Cloud , clique em Abrir ou fechar o chat do Gemini Cloud Assist.

    O painel do Cloud Assist é aberto. Clique nos exemplos de comandos, se eles aparecerem, ou digite um comando no campo Insira um comando.

Confira exemplos de comandos

Para ajudar você a entender como o Gemini Cloud Assist pode ser útil, confira alguns exemplos de comandos:

Tema Cenário Exemplo de comando Como o Gemini Cloud Assist pode ajudar
Configuração inicial Um engenheiro de plataforma está configurando o Config Sync pela primeira vez para gerenciar clusters do GKE em um repositório Git. Como configurar o Config Sync para sincronizar manifestos do meu repositório do GitHub com meu cluster do GKE? O Gemini Cloud Assist oferece um guia detalhado para configurar o Config Sync, abrangendo o registro da frota e a ativação do recurso, além de explicar detalhes como URL do repositório, ramificação, caminho e métodos de autenticação (por exemplo, public, token ou ssh).
Como solucionar erros de sincronização Um desenvolvedor envia um novo manifesto, mas o recurso não é aplicado ao cluster, e o status da sincronização mostra um código de erro. Meu objeto RootSync do Config Sync mostra "KNV2009: the server could not find the requested resource". O que isso significa e como faço para corrigir? O Gemini Cloud Assist analisa o código de erro, explicando que ele geralmente indica que o Config Sync não consegue localizar ou interagir com um recurso esperado do Kubernetes. Em seguida, ele detalha as causas comuns, incluindo permissões RBAC ausentes, limites de tamanho de objetos de recursos excedidos, caminhos de diretório incorretos, conflitos de inventário externo e problemas com recursos não gerenciados, fornecendo etapas específicas de solução de problemas para cada causa.
Gerenciar várias equipes Uma organização precisa permitir que as equipes de aplicativos gerenciem as próprias configurações em namespaces específicos sem dar acesso ao repositório central da plataforma. Qual é a diferença entre um objeto RootSync e um objeto RepoSync no Config Sync? Quando devo usar RepoSync?

O Gemini Cloud Assist explica a principal diferença entre objetos RootSync e RepoSync: os objetos RootSync têm escopo de cluster e geralmente são usados por administradores para configurações em todo o cluster, enquanto os objetos RepoSync têm escopo de namespace e são projetados para que as equipes de aplicativos gerenciem recursos em um namespace específico, promovendo a delegação e a multitenância.

O Gemini Cloud Assist também detalha cenários em que objetos RepoSync devem ser usados, enfatizando os benefícios para multitenancy e redução da área afetada por configurações incorretas.
Validação proativa Um desenvolvedor quer garantir que o novo manifesto seja válido antes de enviá-lo ao repositório para evitar que a sincronização seja interrompida na produção. Como posso verificar se há erros do Config Sync nos meus manifestos do Kubernetes na minha máquina local antes de enviá-los ao repositório Git? O Gemini Cloud Assist explica como verificar manifestos do Kubernetes em busca de erros do Config Sync usando a ferramenta de linha de comando nomos. Ele detalha como usar o comando nomos vet para validação de sintaxe e o comando nomos hydrate para visualizar configurações renderizadas do Kustomize ou do Helm. O Gemini Cloud Assist também descreve um fluxo de trabalho recomendado para integrar essas verificações antes de enviar para o Git.

Para saber mais, acesse os recursos a seguir:

Usar as investigações do Gemini Cloud Assist

Além do chat interativo, o Gemini Cloud Assist pode realizar análises mais automatizadas e detalhadas com o Gemini Cloud Assist Investigations. Esse recurso é integrado diretamente a fluxos de trabalho, como a Análise de registros, e é uma ferramenta poderosa de análise de causa raiz.

Quando você inicia uma investigação de um erro ou recurso específico, o Gemini Cloud Assist analisa registros, configurações e métricas. Ele usa esses dados para produzir observações e hipóteses classificadas sobre prováveis causas principais e, em seguida, fornece as próximas etapas recomendadas. Você também pode transferir esses resultados para um caso de suporte do Google Cloud para fornecer um contexto valioso que pode ajudar a resolver o problema mais rapidamente.

Para mais informações, consulte Investigações do Gemini Cloud Assist na documentação do Gemini.

Conferir outras documentações de solução de problemas

Em caso de problemas persistentes, os recursos a seguir podem ser úteis:

  • Se você tiver recebido uma mensagem de erro, consulte a página de referência de erros para receber conselhos sobre como resolver o problema.

  • Verifique se o erro é causado por um problema conhecido.

  • Se você tiver dificuldades com uma área específica, um dos guias de solução de problemas específicos listados na seção Solução de problemas por tipo de problema da tabela de conteúdos pode ajudar.

A seguir

  • Se você não encontrar uma solução para seu problema na documentação, consulte Receber suporte para mais ajuda, incluindo conselhos sobre os seguintes tópicos: