Resolver problemas de registros ausentes no GKE

Autopilot Standard

Problemas com o pipeline de geração de registros no Google Kubernetes Engine (GKE) podem impedir que os registros do cluster apareçam no Cloud Logging, dificultando seus esforços de monitoramento e depuração.

Use este documento para saber como verificar configurações e permissões, resolver problemas de recursos e desempenho, investigar filtros e comportamento de aplicativos e resolver problemas de plataforma ou serviço que afetam seus registros.

Essas informações são importantes para administradores e operadores de plataforma que mantêm a capacidade de observação do cluster e para qualquer pessoa que use o Cloud Logging para resolver problemas nas operações do GKE. Para mais informações sobre as funções comuns e exemplos de tarefas que mencionamos no conteúdo do Google Cloud , consulte Funções e tarefas comuns do usuário do GKE.

Para mais informações sobre como usar registros para resolver problemas nas cargas de trabalho e nos clusters, consulte Fazer análises históricas com o Cloud Logging.

Encontrar sua solução por sintoma

Se você identificou um sintoma específico relacionado aos registros ausentes, use a tabela a seguir para encontrar dicas de solução de problemas:

Categoria	Sintoma ou observação	Possível causa	Etapas da solução de problemas
Configuração	Nenhum registro de qualquer cluster no projeto é visível.	A API Cloud Logging está desativada para o projeto.	Verificar o status da API Cloud Logging
	Os registros estão faltando em um cluster específico ou apenas alguns tipos de registros estão faltando.	A geração de registros no nível do cluster está desativada para os tipos de registros necessários.	Verificar a configuração de geração de registros do cluster
	Os registros estão faltando nos nós de um pool de nós específico.	Os nós do pool de nós não têm o escopo de acesso necessário.	Verificar escopos de acesso do pool de nós
	Erros de permissão (401 ou 403) aparecem nos registros do agente do Logging.	A conta de serviço do nó não tem a permissão necessária.	Verificar as permissões da conta de serviço do nó
Recurso e performance	Os registros estão faltando de forma intermitente ou você vê erros RESOURCE_EXHAUSTED.	O projeto está excedendo a cota de gravação da API Cloud Logging.	Investigar o uso da cota da API Cloud Logging
	Alguns registros de um nó específico estão faltando, geralmente durante tráfego ou carga altos.	O nó está excedendo os limites de capacidade de processamento do agente do Logging ou não tem recursos (CPU ou memória) para processar registros.	Investigar a taxa de transferência de nós e o uso de recursos
Filtragem e comportamento do aplicativo	Registros específicos que correspondem a um determinado padrão estão sempre ausentes.	Um filtro de exclusão de registros no Cloud Logging está descartando os registros sem querer.	Investigar filtros de exclusão de registros
	Os registros de um contêiner estão significativamente atrasados ou aparecem somente depois que o contêiner é encerrado.	A saída do aplicativo é totalmente armazenada em buffer, geralmente devido ao encadeamento stdout.	Investigar o armazenamento em buffer e os atrasos nos registros de contêineres
	Os registros esperados não aparecem nos resultados da pesquisa.	Os filtros de consulta na Análise de registros podem ser muito restritivos.	Investigar consultas da Análise de registros
	Nenhum registro fica visível em um pod de aplicativo específico, mas outros registros de cluster estão presentes.	O aplicativo dentro do contêiner não está gravando em stdout ou stderr.	Investigar o comportamento de geração de registros específico do aplicativo
Plataforma e serviço	Registros anteriores a uma determinada data não aparecem.	Os registros excederam o período de armazenamento e foram excluídos pelo Cloud Logging.	Investigar períodos de retenção de registros
	Perda ou atrasos generalizados de registros em projetos ou clusters.	Problema no serviço do Cloud Logging ou atraso na ingestão.	Investigar problemas e atrasos no serviço do Cloud Logging
	Os problemas de geração de registros coincidem com as limitações da versão do cluster.	Versão do GKE sem suporte.	Investigar a versão do cluster

Usar ferramentas de diagnóstico automatizadas

As seções a seguir abordam ferramentas que podem inspecionar automaticamente seu cluster em busca de erros de configuração comuns e ajudar a investigar problemas complexos.

Depurar problemas de geração de registros do GKE com gcpdiag

Se você estiver recebendo registros incompletos ou ausentes do cluster do GKE, use a ferramenta gcpdiag para solução de problemas.

gcpdiag é uma ferramenta de código aberto. Não é um produto Google Cloud com suporte oficial. Use a ferramenta gcpdiag para identificar e corrigir problemas no projeto Google Cloud. Para mais informações, consulte o projeto gcpdiag no GitHub.

Quando os registros do cluster do GKE estão ausentes ou incompletos, investigue as causas possíveis focando nas seguintes configurações básicas:

• Geração de registros no nível do projeto:garante que o projeto do Google Cloud que hospeda o cluster do GKE tem a API Cloud Logging ativada.
• Geração de registros no nível do cluster:verifica se a geração de registros está explicitamente ativada na configuração do cluster do GKE.
• Permissões do pool de nós:confirma se os nós nos pools de nós do cluster têm o escopo Cloud Logging Write ativado, permitindo que enviem dados de registro.
• Permissões da conta de serviço:valida se a conta de serviço usada pelos pools de nós tem as permissões de IAM necessárias para interagir com o Cloud Logging. Especificamente, o papel roles/logging.logWriter é normalmente necessário.
• Cotas de gravação da API Cloud Logging:verifica se as cotas de gravação da API Cloud Logging não foram excedidas dentro do período especificado.

Console doGoogle Cloud

1. Preencha e copie o comando a seguir.

gcpdiag runbook gke/logs \
    --parameter project_id=PROJECT_ID \
    --parameter name=CLUSTER_NAME \
    --parameter location=LOCATION

2. Abra o console do Google Cloud e ative o Cloud Shell.
Abrir Console do Cloud
3. Cole o comando copiado.
4. Execute o comando gcpdiag, que faz o download da imagem Docker gcpdiag. e realiza verificações de diagnóstico. Se aplicável, siga as instruções de saída para corrigir verificações com falha.

Docker

Você pode executar gcpdiag usando um wrapper que inicia gcpdiag em um contêiner do Docker. Docker ou Podman precisa ser instalado.

1. Copie e execute o seguinte comando na estação de trabalho local.

   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag

2. Execute o comando gcpdiag.

   ./gcpdiag runbook gke/logs \
       --parameter project_id=PROJECT_ID \
       --parameter name=CLUSTER_NAME \
       --parameter location=LOCATION

Veja os parâmetros disponíveis para este runbook.

Substitua:

• PROJECT_ID: o ID do projeto que contém o recurso.
• CLUSTER_NAME: o nome do cluster do GKE.
• LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.

Flags úteis

• --universe-domain: se aplicável, a Nuvem soberana de parceiro confiável que hospeda o recurso
• --parameter ou -p: parâmetros do runbook

Para conferir uma lista e descrição de todas as flags da ferramenta gcpdiag, consulte Instruções de uso do gcpdiag.

Usar as investigações do Gemini Cloud Assist

Use as investigações do Gemini Cloud Assist para ter mais insights sobre seus registros e resolver problemas. Para mais informações sobre diferentes maneiras de iniciar uma investigação usando o Explorador de registros, consulte Resolver problemas com as investigações do Gemini Cloud Assist na documentação do Gemini.

Verificar a configuração e as permissões de geração de registros

Configurações incorretas são um motivo comum para a ausência de registros do GKE. Use as seções a seguir para verificar sua configuração do Cloud Logging.

Verificar o status da API Cloud Logging

Para que os registros sejam coletados de qualquer cluster no seu projeto, a API Cloud Logging precisa estar ativa.

Sintomas:

Nenhum registro de recursos do GKE no seu projeto está visível no Cloud Logging.

Causa:

A API Cloud Logging está desativada para o projeto Google Cloud , impedindo que o agente de geração de registros nos nós envie registros.

Resolução:

Para verificar se a API Cloud Logging está ativada e ativá-la, se necessário, selecione uma das seguintes opções:

Console

1. No console do Google Cloud , acesse a página APIs e serviços ativados.

   Acessar APIs e serviços ativados

2. No campo Filtro, digite Cloud Logging API e pressione Enter.

3. Se a API estiver ativada, ela vai aparecer na lista. Se a API não estiver listada, ative-a:

   1. Clique em Ativar APIs e serviços.
   2. No campo Pesquisar, digite Cloud Logging API e pressione Enter.
   3. Clique no resultado API Cloud Logging.
   4. Clique em Ativar.

gcloud

1. Verifique se a API está ativada:

   gcloud services list --enabled --filter="NAME=logging.googleapis.com"
   

   A saída vai ser a seguinte:

   NAME: logging.googleapis.com
   TITLE: Cloud Logging API
   

2. Se a API não estiver listada nos serviços ativados, faça o seguinte:

   gcloud services enable logging.googleapis.com \
       --project=PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

Verificar a configuração de geração de registros do cluster

O GKE permite configurar quais tipos de registros (como SYSTEM ou WORKLOAD) são coletados de um cluster.

Sintomas:

Nenhum registro de um cluster específico do GKE aparece no Cloud Logging ou apenas alguns tipos de registros (como SYSTEM) estão ausentes.

Causa:

A geração de registros no nível do cluster está desativada para os tipos de registros necessários. Se você estiver usando um cluster do Autopilot, essa não será a causa dos problemas de geração de registros. Essa configuração pode ser definida para clusters Standard, mas sempre está ativada por padrão em clusters do Autopilot e não pode ser desativada.

Resolução:

Para verificar e atualizar a configuração de geração de registros do cluster, selecione uma das seguintes opções:

Console

1. No console do Google Cloud , acesse a página de clusters do Kubernetes.

   Acessar clusters do Kubernetes

2. Clique no nome do cluster que você quer investigar.

3. Clique na guia Detalhes e navegue até a seção Recursos.

4. Na linha Geração de registros, revise quais tipos de registros, como Sistema ou Cargas de trabalho, estão ativados.

5. Se os tipos de registro que você quer coletar estiverem desativados ou incorretos, clique em Editar geração de registros.

6. Na lista Componentes, marque as caixas de seleção dos tipos de registro que você quer coletar e clique em OK. Para mais informações sobre os tipos de registros disponíveis, consulte Sobre os registros do GKE.

7. Clique em Salvar alterações.

gcloud

1. Para verificar a configuração de geração de registros, descreva o cluster:

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(name,loggingConfig.componentConfig.enableComponents)"
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Se o registro em log estiver ativado, a saída será semelhante a esta:

   example-cluster    SYSTEM_COMPONENTS;WORKLOADS
   

   Se a saída for NONE, a geração de registros estará desativada.

2. Se os tipos de registros que você quer estiverem desativados ou incorretos, atualize a configuração de geração de registros:

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=LOGGING_TYPE
   

   Substitua LOGGING_TYPE por SYSTEM, WORKLOAD ou ambos. Para coletar registros, o SYSTEM precisa estar ativado. Os registros do WORKLOAD não podem ser coletados por conta própria. Para mais informações sobre os tipos de registros disponíveis, consulte Sobre os registros do GKE.

Verificar os escopos de acesso do pool de nós

Os nós em um cluster do GKE usam escopos de acesso do OAuth para receber permissão de interagir com as APIs do Google Cloud , incluindo o Cloud Logging.

Sintomas:

Os registros estão faltando em nós de um pool de nós específico.

Causa:

Os nós no pool de nós não têm o escopo de acesso do OAuth necessário. Um dos escopos a seguir é necessário para que os nós gravem registros no Cloud Logging:

• https://www.googleapis.com/auth/logging.write: concede permissão para gravar registros. Esse é o escopo mínimo necessário.
• https://www.googleapis.com/auth/logging.admin: concede acesso total à API Cloud Logging, que inclui as permissões de logging.write.
• https://www.googleapis.com/auth/cloud-platform: concede acesso total a todas as APIs Google Cloud ativadas, incluindo as permissões de logging.write.

Resolução:

Para verificar as permissões e conceder as funções necessárias, se estiverem faltando, selecione uma das seguintes opções:

Console

1. Verifique os escopos de acesso do pool de nós:

   1. No console do Google Cloud , acesse a página de clusters do Kubernetes.

      Acessar clusters do Kubernetes

   2. Para abrir a página de detalhes do cluster, clique no nome do cluster que você quer investigar.

   3. Clique na guia Nós.

   4. Na seção Pools de nós, clique no nome do pool de nós que você quer investigar.

   5. Navegue até a seção Segurança.

   6. Revise os escopos listados no campo Escopos de acesso. Verifique se pelo menos um dos escopos obrigatórios está presente:

      • API Stackdriver Logging: somente gravação
      • API Stackdriver Logging: total
      • Cloud Platform: ativado

      Se os escopos necessários estiverem faltando, recrie o pool de nós. Não é possível mudar os escopos de acesso em um pool de nós atual.

2. Se necessário, crie um pool de nós com o escopo necessário:

   1. Volte à página de detalhes do cluster que você quer modificar.
   2. Clique na guia Nós.
   3. Clique em Criar pool de nós gerenciado pelo usuário.
   4. Preencha a seção Detalhes do pool de nós.
   5. Na navegação à esquerda, clique em Segurança.
   6. Na seção Escopos de acesso, selecione as funções que você quer adicionar:
      • Para adicionar escopos específicos, selecione Definir acesso para cada API.
      • Para permitir acesso total, selecione Permitir acesso total a todas as APIs do Cloud.
   7. Configure outras seções conforme necessário.
   8. Clique em Criar.

3. Migre suas cargas de trabalho para o novo pool de nós. Depois de migrar as cargas de trabalho para o novo pool de nós, os aplicativos serão executados em nós com os escopos necessários para enviar registros ao Cloud Logging.

4. Exclua o pool de nós antigo:

   1. Volte para a página de detalhes do cluster e selecione a guia Nós.
   2. Na seção Pools de nós, encontre o pool de nós antigo.
   3. Ao lado do pool de nós, clique em Excluir .
   4. Quando solicitado, confirme a exclusão digitando o nome do pool de nós e clique em Excluir.

gcloud

1. Verifique os escopos de acesso do pool de nós:

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePools[].name,nodePools[].config.oauthScopes)"
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
   • PROJECT_ID: o ID do projeto Google Cloud .

   Analise a saída de cada pool de nós. Verifique se pelo menos um dos escopos obrigatórios (https://www.googleapis.com/auth/logging.write, https://www.googleapis.com/auth/cloud-platform ou https://www.googleapis.com/auth/logging.admin) está listado. Se os escopos necessários estiverem faltando, recrie o pool de nós. Não é possível mudar os escopos de acesso em um pool de nós atual.

2. Se necessário, crie um pool de nós com o escopo necessário:

   gcloud container node-pools create NEW_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --scopes=https://www.googleapis.com/auth/logging.write,OTHER_SCOPES
   

   Substitua:

   • NEW_NODE_POOL_NAME: um nome para o novo pool de nós.
   • OTHER_SCOPES: uma lista separada por vírgulas de outros escopos necessários para seus nós. Se você não precisar de outros escopos, omita esse marcador de posição e a vírgula anterior.

3. Migre suas cargas de trabalho para o novo pool de nós. Depois de migrar as cargas de trabalho para o novo pool de nós, os aplicativos serão executados em nós com os escopos necessários para enviar registros ao Cloud Logging.

4. Exclua o pool de nós antigo:

   gcloud container node-pools delete OLD_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID
   

Verificar as permissões da conta de serviço do nó

Os nós usam uma conta de serviço para autenticar com os serviços do Google Cloud , e essa conta precisa de permissões específicas do IAM para gravar registros.

Sintomas:

• Os registros estão faltando nos nós.
• A inspeção dos registros do agente de geração de registros (por exemplo, Fluent Bit) pode mostrar erros relacionados a permissões, como códigos 401 ou 403 ao tentar gravar no Cloud Logging.
• Talvez você veja uma notificação Grant Critical Permissions to Node Service Account para o cluster no console do Google Cloud .

Causa:

A conta de serviço usada pelos nós do pool de nós não tem as permissões do IAM necessárias para gravar registros no Cloud Logging. Os nós exigem uma conta de serviço com o papel logging.logWriter, que inclui a permissão logging.logEntries.create.

Além disso, para versões do GKE 1.33 ou mais recentes, o Agente de serviço de nó padrão do GKE ([e-mail]) precisa ter, no mínimo, o papel de Agente de serviço de nó padrão do Kubernetes (roles/container.defaultNodeServiceAgent). Com essa função, o GKE gerencia recursos e operações de nós, incluindo componentes de geração de registros.

Resolução:

Para verificar as permissões e conceder as funções necessárias, faça o seguinte:

• Verifique a permissão da conta de serviço do nó.
• Verifique se o agente de serviço do GKE tem o papel necessário.

Verificar a permissão da conta de serviço do nó

A conta de serviço do nó é a conta usada pelo nó para autenticar e enviar registros. Para identificar essa conta de serviço e verificar se ela tem a permissão roles/logging.logWriter necessária, faça o seguinte:

1. Para identificar a conta de serviço usada pelo pool de nós, selecione uma das seguintes opções:

   Console

   1. No console do Google Cloud , acesse a página de clusters do Kubernetes.

      Acessar clusters do Kubernetes

   2. Na lista de clusters, clique no nome do cluster que você quer inspecionar.

   3. Dependendo do modo de operação do cluster, faça o seguinte:

      • Para clusters padrão, faça o seguinte:

        1. Clique na guia Nós.
        2. Na tabela Pools de nós, clique no nome de um pool de nós. A página "Detalhes do pool de nós" é aberta.
        3. Na seção Segurança, encontre o campo Conta de serviço.

      • Para clusters do Autopilot, faça o seguinte:

        1. Acesse a guia Detalhes.
        2. Na seção Segurança, encontre o campo Conta de serviço.

      Se o valor no campo Conta de serviço for default, seus nós usarão a conta de serviço padrão do Compute Engine. Se o valor neste campo não for default, seus nós usarão uma conta de serviço personalizada. Para conceder o papel necessário a uma conta de serviço personalizada, consulte Usar contas de serviço do IAM com privilégio mínimo.

   gcloud

   Execute o seguinte comando, dependendo do tipo de cluster que você usa:

   Clusters padrão

   gcloud container node-pools describe NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(config.serviceAccount)"
   

   Substitua:

   • NODE_POOL_NAME: o nome do pool de nós.
   • CLUSTER_NAME: o nome do cluster padrão.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
   • PROJECT_ID: o ID do projeto do Google Cloud.

   Se a saída for default, o pool de nós usará a conta de serviço padrão do Compute Engine. Se o valor não for default, seus nós usarão uma conta de serviço personalizada. Para conceder o papel necessário a uma conta de serviço personalizada, consulte Usar contas de serviço do IAM privilégio mínimo mínimos.

   Clusters do Autopilot

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePoolDefaults.nodeConfigDefaults.serviceAccount)"
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster do Autopilot.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.
   • PROJECT_ID: o ID do projeto do Google Cloud .

   Se a saída for default, o pool de nós usará a conta de serviço padrão do Compute Engine. Se o valor não for default, seus nós usarão uma conta de serviço personalizada. Para conceder o papel necessário a uma conta de serviço personalizada, consulte Usar contas de serviço do IAM privilégio mínimo mínimos.

   Para scripts mais detalhados que identificam permissões ausentes, consulte Identificar todas as contas de serviço do nó com permissões ausentes.

2. O GKE verifica automaticamente se há permissões ausentes e fornece recomendações. Para usar recomendações e verificar se há permissões ausentes, selecione uma das seguintes opções:

   Console

   1. Na página Clusters do Kubernetes, localize a coluna Notificações.
   2. Verifique a coluna Notificações para a recomendação Conceder permissões críticas. Essa recomendação significa que a verificação NODE_SA_MISSING_PERMISSIONS falhou.
   3. Se a recomendação aparecer, clique nela. Um painel de detalhes é aberto, explicando as permissões ausentes e fornecendo as etapas para corrigir o problema.

   gcloud

   1. Liste as recomendações de permissões ausentes da conta de serviço:

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. Analise a resposta ao comando:

      • Se o comando retornar uma lista vazia, o recomendador não encontrou nenhuma recomendação NODE_SA_MISSING_PERMISSIONS ativa. As contas de serviço verificadas parecem ter as permissões necessárias.

      • Se o comando retornar um ou mais blocos YAML, o recomendador identificou um problema de permissão. Analise a saída nos seguintes campos principais:

        • description: fornece um resumo do problema, como especificar que a conta de serviço do nó não tem o papel roles/logging.logWriter ou que o agente de serviço do GKE não tem o papel roles/container.defaultNodeServiceAgent.
        • resource: especifica o cluster afetado.
        • content.operations: contém a resolução recomendada. Esta seção fornece o comando gcloud projects add-iam-policy-binding exato necessário para conceder a função específica que está faltando.

   O recomendador pode levar até 24 horas para refletir as mudanças recentes.

3. Se você quiser verificar as permissões imediatamente, selecione uma das seguintes opções:

   Console

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

      Acessar IAM

   2. Encontre a conta de serviço usada pelo pool de nós.

   3. Na coluna Papel, verifique se a conta de serviço tem o papel de Gravador de registros (roles/logging.logWriter).

   4. Se a permissão estiver ausente, adicione-a:

      1. Clique em Editar principal.
      2. Clique em Adicionar outro papel.
      3. No Logs Writer campo de pesquisa, insira .
      4. Marque a caixa de seleção Gravador de registros e clique em Aplicar.
      5. Clique em Salvar.

   gcloud

   1. Verifique os papéis atuais da conta de serviço do nó:

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT_EMAIL"
      

   2. Se ele não estiver lá, conceda o papel logging.logWriter:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/logging.logWriter"
      

Verificar as permissões do agente de serviço do GKE

Se os registros ainda estiverem faltando e você usar a versão 1.33 ou mais recente, verifique se o agente gerenciado pelo Google que o GKE usa para gerenciar os componentes do nó tem a permissão necessária:

1. Para identificar o endereço de e-mail do agente de serviço, encontre o número do projeto:

   gcloud projects describe PROJECT_ID --format="value(projectNumber)"
   

   Substitua PROJECT_ID pelo código do seu projeto. Observe a saída.

   O e-mail do agente de serviço do GKE é: [e-mail]

2. Para usar recomendações e verificar se há permissões ausentes, selecione uma das seguintes opções:

   Console

   1. Na página Clusters do Kubernetes, encontre a coluna Notificações.
   2. Verifique a coluna da recomendação Conceder permissões essenciais.
   3. Se a recomendação aparecer, clique nela. Um painel de detalhes é aberto, explicando as permissões ausentes e fornecendo as etapas para corrigir o problema.

   gcloud

   1. Liste as recomendações de permissões ausentes da conta de serviço:

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. Analise a resposta ao comando. Analise a saída para ver uma descrição especificando que o agente de serviço do GKE (gcp-sa-gkenode) não tem o papel roles/container.defaultNodeServiceAgent.

3. Para verificar as permissões e conceder a função imediatamente, selecione uma das seguintes opções:

   Console

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

      Acessar IAM

   2. No campo Filtro, digite o endereço de e-mail do agente de serviço do GKE e pressione Enter.

   3. Na lista filtrada, verifique se o agente de serviço tem pelo menos o papel Agente de serviço de nó padrão do Kubernetes (roles/container.defaultNodeServiceAgent).

   4. Se o papel estiver faltando, conceda-o:

      1. Clique em Editar principal ao lado do agente de serviço.
      2. Clique em Adicionar funções.
      3. No campo de pesquisa, insira Kubernetes Default Node Service Agent e selecione a função.
      4. Clique em Salvar.

   gcloud

   1. Verifique se o papel roles/container.defaultNodeServiceAgent está vinculado ao agente de serviço:

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:[e-mail]"
      

      Na saída, procure roles/container.defaultNodeServiceAgent.

   2. Se a função estiver faltando, conceda o papel de agente de serviço de nó padrão do Kubernetes:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:[e-mail]" \
          --role="roles/container.defaultNodeServiceAgent"
      

Resolver problemas de recursos e desempenho

Se os registros estiverem faltando de forma intermitente ou forem descartados de nós de alto tráfego, a causa pode não ser uma configuração incorreta, mas um problema de desempenho. Use as seções a seguir para investigar se o projeto está excedendo as cotas de API ou se o alto volume de registros está sobrecarregando os agentes em nós específicos.

Investigar o uso da cota da API Cloud Logging

Para proteger o serviço, o Cloud Logging impõe uma cota de gravação em todos os projetos, limitando o volume total de registros que o Cloud Logging pode ingerir por minuto.

Sintomas:

• Os registros estão faltando de forma intermitente ou completa.
• Você vê erros RESOURCE_EXHAUSTED relacionados a logging.googleapis.com nos registros do agente de nós ou de geração de registros.

Causa:

O projeto está excedendo a cota de solicitações de gravação da API Cloud Logging. Esse problema impede que o agente do Logging envie registros.

Resolução:

Para verificar o uso da cota e solicitar um aumento, faça o seguinte:

1. No Google Cloud console, acesse a página Cotas.

   Acesse Cotas

2. No campo Filtro, digite Cloud Logging API e pressione Enter.

3. Na lista filtrada, encontre a cota de Bytes de gravação no registro por minuto e por região para a região em que seu cluster está.

4. Analise os valores na coluna Porcentagem de uso atual. Se o uso estiver no limite ou perto dele, provavelmente você excedeu a cota.

5. Para solicitar um aumento, clique em Editar cota e siga as instruções. Para mais informações, consulte Ver e gerenciar cotas.

Para reduzir o uso, considere excluir registros ou reduzir o nível de detalhe dos registros dos aplicativos. Também é possível configurar políticas de alertas para receber notificações antes de atingir o limite.

Investigar a capacidade do nó e o uso de recursos

O agente de geração de registros do GKE em cada nó tem um limite de capacidade próprio, que pode ser excedido.

Sintomas:

Os registros de nós específicos ficam faltando ou atrasados de forma intermitente, principalmente durante períodos de alta atividade do cluster ou uso intenso de recursos do nó.

Causa:

O agente de geração de registros do GKE tem um limite de capacidade de processamento padrão (aproximadamente 100 KBps por nó). Se os aplicativos em um nó gerarem registros mais rápido do que esse limite, o agente poderá descartar registros, mesmo que a cota geral da API do projeto não seja excedida. É possível monitorar a capacidade de processamento de registros de nós usando a métrica kubernetes.io/node/logs/input_bytes no Metrics Explorer.

Os registros também podem estar ausentes se o nó estiver sob forte pressão de CPU ou memória, deixando recursos insuficientes para o agente processar os registros.

Resolução:

Para reduzir a capacidade de transmissão, selecione uma das seguintes opções:

Clusters padrão

Tente as seguintes soluções:

• Ativar a geração de registros de alta capacidade de processamento: esse recurso aumenta a capacidade por nó. Para mais informações, consulte Ajustar a capacidade agente do Logging do Cloud Logging.

• Reduza o volume de registros: analise os padrões de registro de aplicativos. Reduza o registro em excesso ou desnecessário.

• Implante um agente de geração de registros personalizado: é possível implantar e gerenciar seu próprio DaemonSet do Fluent Bit personalizado, mas você é responsável pela configuração e manutenção dele.

• Verifique o uso de recursos do nó: mesmo que o volume de registros esteja dentro dos limites, verifique se os nós não estão sob pressão excessiva de CPU ou memória. Recursos insuficientes de nó podem prejudicar a capacidade do agente de geração de registros de processar e enviar registros. Você pode verificar métricas como kubernetes.io/node/cpu/core_usage_time e kubernetes.io/node/memory/used_bytes no Metrics Explorer.

Clusters do Autopilot

Tente as seguintes soluções:

• Reduza o volume de registros: analise os padrões de registro do aplicativo. Reduza o registro em excesso ou desnecessário. Sempre que possível, estruture os registros, porque eles ajudam no processamento eficiente. Exclua registros que não são essenciais.

• Otimize o desempenho do aplicativo: como os recursos do nó são gerenciados em clusters do Autopilot, verifique se os aplicativos não estão consumindo CPU ou memória em excesso, o que pode afetar indiretamente o desempenho de componentes do nó, como o agente de geração de registros. Embora você não gerencie os nós diretamente, a eficiência do aplicativo afeta a integridade geral deles.

Resolver problemas de filtragem e aplicativos

Quando o aplicativo gera registros com êxito, mas eles ainda não aparecem no Cloud Logging, o problema geralmente é causado por filtragem ou pelo comportamento de registro do aplicativo. As seções a seguir abordam problemas como filtros de exclusão de registros, armazenamento em buffer no nível do contêiner, consultas de pesquisa restritivas e aplicativos que não gravam em stdout ou stderr.

Investigar filtros de exclusão de registros

O Buscador de registros mostra apenas os registros que correspondem a todos os filtros na sua consulta e ao período selecionado.

Sintomas:

Registros específicos que correspondem a determinados critérios estão ausentes do Cloud Logging, mas outros registros das mesmas fontes estão presentes.

Causa:

Os filtros de exclusão de registros são definidos nos coletores do Cloud Logging (geralmente o coletor _Default). Essas regras descartam silenciosamente os registros que correspondem a critérios específicos, mesmo que tenham sido enviados pelo nó.

Resolução:

Para analisar e modificar filtros de exclusão, selecione uma das seguintes opções:

Console

1. No console do Google Cloud , acesse a página Roteador de registros.

   Acessar o roteador de registros

2. Identifique o filtro problemático:

   1. Para cada coletor (exceto o _Required, que não pode ter filtros de exclusão), clique em Mais ações e selecione Ver detalhes do coletor.
   2. Analise as consultas na seção Filtros de exclusão. Compare a lógica do filtro com os atributos dos registros ausentes (por exemplo, tipo de recurso, rótulos ou palavras-chave).
   3. Copie a consulta do filtro de exclusão.

   4. Acesse a página Análise de registros.

      Acessar a Análise de registros

   5. Cole a consulta de filtro de exclusão no painel de consultas e clique em Executar consulta.

   6. Analise os resultados. Os registros mostrados são aqueles que o filtro excluiria. Se os registros ausentes aparecerem nesses resultados, é provável que esse filtro seja a causa.

3. Desative ou edite o filtro:

   1. Volte para a página Roteador de registros.
   2. Clique em Mais ações no coletor com o filtro suspeito e selecione Editar coletor.
   3. Localize a seção Escolher registros para filtrar do coletor e encontre o filtro de exclusão.
   4. Clique em Desativar para desativar o filtro ou modifique a consulta para ser mais específica.
   5. Clique em Atualizar coletor. As mudanças são aplicadas a novos registros.

gcloud

1. Liste todos os coletores no projeto:

   gcloud logging sinks list --project=PROJECT_ID
   

2. Confira os filtros de exclusão de cada coletor:

   gcloud logging sinks describe SINK_NAME --project=PROJECT_ID
   

   Na saída, revise a seção exclusions. Compare a lógica do filtro com os atributos dos registros ausentes (por exemplo, tipo de recurso, rótulos ou palavras-chave).

3. Para modificar exclusões, atualize a configuração do coletor:

   1. Exporte a configuração do gravador para um arquivo local (por exemplo, sink-config.yaml):

      gcloud logging sinks describe SINK_NAME \
          --format=yaml > sink-config.yaml
      

   2. Abra o arquivo sink-config.yaml em um editor de texto.

   3. Encontre a seção exclusions: e remova ou modifique o filtro problemático.

   4. Atualize o coletor modificado:

      gcloud logging sinks update SINK_NAME sink-config.yaml \
          --project=PROJECT_ID
      

      Para mais informações sobre esse comando, consulte a documentação de gcloud logging sinks update.

Investigar o buffer e os atrasos de registros de contêineres

Aplicativos e sistemas operacionais geralmente usam buffer para gravar dados em partes em vez de linha por linha, o que pode melhorar o desempenho.

Sintomas:

• Os registros de contêineres específicos aparecem no Cloud Logging somente depois que o contêiner é encerrado ou há um atraso significativo na exibição dos registros.
• Às vezes, os registros estão incompletos.

Causa:

Esse problema geralmente é causado pelo buffer de registros. Embora a saída padrão (stdout) seja normalmente armazenada em buffer de linha quando conectada a um terminal, esse comportamento muda quando a saída é redirecionada. Se os registros ou scripts de inicialização de um aplicativo em um pipeline de contêiner transmitirem stdout para outros comandos (por exemplo, my-app | grep ...), a saída poderá ficar totalmente armazenada em buffer. Como resultado, os registros são mantidos até que o buffer esteja cheio ou o pipe seja fechado. Esse comportamento pode causar atrasos ou perda de dados se o contêiner for encerrado inesperadamente. O armazenamento em buffer interno do aplicativo também pode causar atrasos.

Resolução:

Para resolver o problema, tente as seguintes soluções:

• Evite o encadeamento de stdout: se possível, modifique os pontos de entrada do contêiner ou os comandos do aplicativo para gravar registros diretamente em stdout ou stderr sem encadeamento por outros comandos, como grep ou sed, no contêiner.
• Garantir o buffer de linha:
  • Se o encanamento for inevitável, use ferramentas que ofereçam suporte ao buffer de linha. Por exemplo, use grep --line-buffered.
  • Para aplicativos personalizados, verifique se eles liberam registros com frequência, de preferência após cada linha, ao gravar em stdout. Muitas bibliotecas de geração de registros têm configurações para controlar o buffer.

• Teste o comportamento de buffer: implante o manifesto do pod a seguir e observe os efeitos nos registros usando o comando kubectl logs -f buffered-pod. Teste comentando e removendo o comentário das diferentes matrizes command no manifesto buffered-container:

  # buffered.yaml
  apiVersion: v1
  kind: ConfigMap
  metadata:
  name: run-script
  data:
  run.sh: |
      #!/bin/bash
      echo "Starting..."
      for i in $(seq 3600); do
      echo "Log ${i}"
      sleep 1
      done
      echo "Exiting."
  ---
  apiVersion: v1
  kind: Pod
  metadata:
  name: buffered-pod
  spec:
  containers:
      - name: buffered-container
      image: ubuntu  # Or any other image with bash
  
      # Case 1: Direct execution - line buffered by default to TTY
      # Logs appear immediately.
      command: ['/bin/bash', '-c', '/mnt/run.sh']
  
      # Case 2: Piped to grep - fully buffered by default
      # Logs might be delayed or appear in chunks.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep Log']
  
      # Case 3: Piped to grep with --line-buffered
      # Logs appear immediately.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep --line-buffered Log']
  
      volumeMounts:
          - name: scripts
          mountPath: /mnt
  volumes:
      - name: scripts
      configMap:
          name: run-script
          defaultMode: 0777
  restartPolicy: Never
  

Investigar consultas da Análise de registros

Se você tiver certeza de que os registros estão sendo coletados, mas não consegue encontrá-los, o problema pode estar na consulta de pesquisa ou no período.

Sintomas:

Os registros esperados não aparecem nos resultados da pesquisa, mesmo que você saiba que o aplicativo os está gerando.

Causa:

Sua consulta no Explorador de registros pode ter filtros (por exemplo, em namespaces, rótulos, tipos de recursos ou texto) que excluem inadvertidamente os registros que você está procurando.

Resolução:

1. No console do Google Cloud , acesse a página Análise de registros.

   Acessar a Análise de registros

2. Clique em Escolher período. Mesmo que você ache que sabe quando os registros ocorreram, tente um período muito mais amplo para descartar problemas de tempo.

3. Simplifique a consulta:

   1. Limpe todos os filtros.

   2. Tente filtrar apenas pelo seu cluster:

      resource.type="k8s_container"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      

      Substitua:

      • CLUSTER_NAME: o nome do cluster.
      • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.

   3. Clique em Executar consulta.

4. Se a consulta ampla funcionar, reintroduza os filtros originais um por um:

   • Tipo de recurso: use o tipo de recurso correto. Por exemplo, você está filtrando por k8s_container quando deveria filtrar por k8s_node?
   • Rótulos: verifique a ortografia de resource.labels, como namespace_name, container_name ou rótulos personalizados.
   • Gravidade: verifique se o nível de gravidade (por exemplo, severity=ERROR) não é muito restritivo.
   • Payload de texto: verifique se há erros de ortografia e strings excessivamente restritivas em termos de pesquisa. Por exemplo, use : para "contém" em vez de = para uma correspondência exata (jsonPayload.message:"error" em vez de jsonPayload.message="error").

5. Verifique se os filtros consideram a sensibilidade a maiúsculas e minúsculas (o texto geralmente não diferencia maiúsculas de minúsculas, mas os rótulos podem diferenciar), se os valores não têm caracteres ocultos ou espaços extras e se os termos com caracteres especiais precisam ser colocados entre aspas.

6. Revise a Linha do tempo. Quedas repentinas ao adicionar um filtro podem ajudar a identificar a parte problemática da consulta.

Para mais dicas sobre consultas de registros eficazes, consulte Como localizar entradas de registro rapidamente na documentação do Cloud Logging.

Se você ainda não conseguir encontrar os registros depois de refinar a consulta, o problema pode não ser a consulta, mas um problema descrito em outras seções deste documento.

Investigar o comportamento de geração de registros específico do aplicativo

O agente do Logging do GKE coleta apenas registros gravados nos fluxos stdout e stderr.

Sintomas:

Nenhum registro de um pod ou contêiner específico está visível no Cloud Logging, mesmo que outros registros do cluster estejam presentes.

Causa:

O aplicativo não está gravando em stdout ou stderr. Ele pode estar mal configurado para gravar registros em um arquivo dentro do contêiner, onde o agente de geração de registros não pode coletá-los.

O aplicativo também pode estar misturando texto JSON e não JSON na saída. O analisador do agente de registro espera um formato consistente (JSON ou texto) de um único fluxo. Se um aplicativo configurado para geração de registros JSON gerar uma linha de texto simples, isso pode interromper o analisador, fazendo com que os registros sejam descartados ou ingeridos incorretamente.

Resolução:

1. Determine o nome do pod e o namespace do aplicativo cujos registros estão ausentes:

   kubectl get pods -n NAMESPACE_NAME
   

2. Verifique os registros do contêiner:

   • Se o pod tiver um único contêiner, execute o seguinte comando:

     kubectl logs POD_NAME \
         -n NAMESPACE_NAME
     

     Substitua:

     • POD_NAME: o nome do pod.
     • NAMESPACE_NAME: o namespace do pod.

   • Se o pod tiver vários contêineres, especifique o nome do contêiner:

     kubectl logs POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     Substitua CONTAINER_NAME pelo nome do contêiner no pod.

   • Para acompanhar os registros em tempo real, execute o seguinte comando:

     kubectl logs -f POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     Substitua:

     • POD_NAME: o nome do pod.
     • CONTAINER_NAME: o nome do contêiner no pod.
     • NAMESPACE_NAME: o namespace do pod.

3. Analise a saída:

   • Se o comando kubectl logs não tiver saída ou se resposta ao comando não contiver os registros esperados, o problema será com o aplicativo em si. O comando kubectl logs lê diretamente os fluxos stdout e stderr capturados pelo ambiente de execução do contêiner. Se os registros não estiverem aqui, o agente de geração de registros do GKE não poderá vê-los.

     Mude o código ou a configuração do aplicativo para parar de gravar em um arquivo e, em vez disso, registre todas as mensagens diretamente em stdout (para registros regulares) e stderr (para registros de erros).

   • Se você encontrar uma mistura de strings JSON e linhas de texto simples, essa saída indica um problema de formato misto. Configure seu aplicativo para gravar apenas objetos JSON válidos de uma única linha em stdout e stderr.

   • Se o comando kubectl logs mostrar os registros esperados, o problema provavelmente está mais abaixo no pipeline de geração de registros (por exemplo, agente, permissões ou serviço do Cloud Logging).

Resolver problemas de plataforma e serviço

As seções a seguir ajudam você a investigar problemas externos à sua configuração imediata, como políticas de retenção de registros, integridade do Cloud Logging ou versões incompatíveis do GKE.

Investigar períodos de retenção de registros

Os registros são armazenados em buckets, e cada um deles tem um período de armazenamento que define por quanto tempo os registros são mantidos antes de serem excluídos automaticamente.

Sintomas:

Os registros anteriores a uma determinada data estão ausentes.

Causa:

Os registros que você está procurando são mais antigos do que o período de armazenamento do bucket de registros para onde foram encaminhados.

Resolução:

Para identificar e atualizar o período de armazenamento, selecione uma das seguintes opções:

Console

1. Identifique o bucket para onde os registros do GKE são encaminhados:

   1. No console do Google Cloud , acesse a página Roteador de registros.

      Acessar o roteador de registros

   2. Revise a coluna Destino, que mostra para onde os registros estão sendo roteados.

      O destino será semelhante a este:

      logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
      

      Observe PROJECT_ID, LOCATION e BUCKET_ID.

      Os registros geralmente são roteados para o bucket _Default, mas também podem ser roteados para outros buckets se você tiver coletores personalizados configurados.

2. Verifique o período de armazenamento do bucket de registros:

   1. No console Google Cloud , acesse a página Armazenamento de registros.

      Acessar o armazenamento de registros

   2. Encontre os buckets correspondentes a BUCKET_ID, LOCATION e PROJECT_ID no destino do coletor.

   3. Para cada bucket relevante, consulte a coluna Período de retenção.

   4. Se os registros que você quer ver forem mais antigos que o período de retenção, o Cloud Logging os terá excluído. Se você precisar de um período de armazenamento mais longo, faça o seguinte:

      1. No bucket cujo período de armazenamento você quer estender, clique em Mais ações.
      2. Selecione Editar bucket e atualize o período de armazenamento. Esteja ciente das implicações de custos.

gcloud

1. Identifique o bucket para onde os registros do GKE são encaminhados:

   gcloud logging sinks list --project=PROJECT_ID
   

   Verifique a saída. O campo destination de cada gravador mostra para onde os registros estão sendo encaminhados. O formato de destino de um bucket de registros é:

   logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
   

   Observe PROJECT_ID, LOCATION e BUCKET_ID.

   Os registros geralmente são encaminhados para o bucket _Default.

2. Verifique o período de armazenamento do bucket de registros:

   gcloud logging buckets describe BUCKET_ID \
       --location=LOCATION \
       --project=PROJECT_ID
   

   Na saída, procure o campo retentionDays. Se os registros que você precisa forem mais antigos que o valor listado para retentionDays, o Cloud Logging os terá excluído.

3. Se você precisar de um período de armazenamento mais longo, atualize-o:

   gcloud logging buckets update BUCKET_ID \
       --location=LOCATION \
       --retention-days=RETENTION_DAYS \
       --project=PROJECT_ID
   

   Substitua:

   • BUCKET_ID: o ID do bucket de registros.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do bucket.
   • RETENTION_DAYS: o número de dias para reter os registros. Esteja ciente das implicações de custo de aumentar o período de armazenamento.
   • PROJECT_ID: o ID do projeto Google Cloud .

Investigar problemas de serviço e atrasos na ingestão do Cloud Logging

Às vezes, o próprio pipeline de geração de registros pode ter problemas, seja por uma interrupção em todo o serviço ou por um atraso temporário e em grande escala na ingestão.

Sintomas:

• Perda de registros generalizada ou intermitente em vários projetos ou clusters.
• Os registros demoram muito para aparecer na Análise de registros.

Causa:

• Interrupção do serviço do Cloud Logging: uma interrupção rara em todo o serviço pode impedir a ingestão de registros, causando atrasos generalizados ou perda total de registros.
• Alto volume de registros: mesmo sem uma interrupção oficial, um alto volume de registros do seu projeto ou região pode sobrecarregar temporariamente o serviço de ingestão, causando atrasos na exibição dos registros.

Resolução:

• Confira o status dos serviços do Google Cloud no painel de integridade do serviço.Google CloudProcure incidentes abertos relacionados ao Cloud Logging ou ao GKE.

• Considere possíveis atrasos na ingestão. Se os registros não estiverem visíveis imediatamente e não houver incidentes ativos, aguarde um pouco para a ingestão, principalmente se o volume de registros for alto. Tente de novo em alguns minutos.

Investigar a versão do cluster

O GKE lança regularmente novas versões que incluem correções de bugs e melhorias de performance para componentes, incluindo o agente de geração de registros.

Sintomas:

Os problemas de geração de registros coincidem com as limitações da versão do cluster.

Causa:

O cluster pode estar executando uma versão mais antiga ou sem suporte do GKE que tem problemas conhecidos com o agente de geração de registros ou não tem determinados recursos de geração de registros.

Resolução:

Para resolver esse problema, faça o seguinte:

1. Verifique a versão do cluster:

   gcloud container clusters describe CLUSTER_NAME \
       --location LOCATION \
       --format="value(currentMasterVersion)"
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • LOCATION: a região ou zona do Compute Engine (por exemplo, us-central1 ou us-central1-a) do cluster.

2. Para garantir que seja uma versão compatível, compare com a programação de lançamento do GKE.

3. Se o cluster estiver usando uma versão sem suporte, faça upgrade dele.

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:

  • Abrir um caso de suporte entrando em contato com o Cloud Customer Care.
  • Receber suporte da comunidade fazendo perguntas no StackOverflow e usando a tag google-kubernetes-engine para pesquisar problemas semelhantes. Você também pode participar do canal do Slack #kubernetes-engine para receber mais suporte da comunidade.
  • Abrir bugs ou solicitações de recursos usando o Issue Tracker público.