Resolver problemas do Config Connector

Nesta página, descrevemos técnicas de solução de problemas que você pode usar para resolver problemas do Config Connector e problemas comuns que podem ocorrer ao usar o produto.

Verificar o status e as condições do Config Connector

Verificar a versão do Config Connector

Execute o comando a seguir para ver a versão instalada do Config Connector e consulte as notas da versão para verificar se a versão em execução é compatível com os recursos que você quer usar:

kubectl get ns cnrm-system -o jsonpath='{.metadata.annotations.cnrm\.cloud\.google\.com/version}'

Verificar o status e os eventos do recurso

Normalmente, é possível determinar o problema com os recursos do Config Connector inspecionando o estado dos recursos no Kubernetes. Verificar o status e os eventos de um recurso é especialmente útil para determinar se o Config Connector não reconciliou o recurso e por que a reconciliação falhou.

Verificar se o Config Connector está em execução

Para verificar se o Config Connector está em execução, confira se todos os pods dele estão READY:

kubectl get pod -n cnrm-system

Exemplo de saída:

NAME                                            READY   STATUS    RESTARTS   AGE
cnrm-controller-manager-0                       1/1     Running   0          1h
cnrm-deletiondefender-0                         1/1     Running   0          1h
cnrm-resource-stats-recorder-77dc8cc4b6-mgpgp   1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-pqwhz           1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-wdcn4           1/1     Running   0          1h

Se o Config Connector estiver instalado no modo de namespace, você terá um pod de controlador (cnrm-controller-manager) para cada namespace responsável por gerenciar os recursos do Config Connector nesse namespace.

Para verificar o status do pod do controlador responsável por um namespace específico, execute:

kubectl get pod -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager

Substitua NAMESPACE pelo nome do namespace.

Verificar os registros do controlador

O pod do controlador registra informações e erros relacionados à reconciliação de recursos do Config Connector.

Para verificar os registros do pod do controlador, execute:

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

Se o Config Connector estiver instalado no modo de namespace, o comando anterior vai mostrar os registros de todos os pods do controlador combinados. Verifique os registros do pod do controlador para um namespace específico executando:

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

Substitua NAMESPACE pelo nome do namespace.

Leia mais sobre como inspecionar e consultar os registros do Config Connector.

Abandonar e adquirir o recurso

Em alguns casos, pode ser necessário atualizar um campo imutável em um recurso. Como não é possível editar campos imutáveis, você precisa abandonar e adquirir o recurso novamente:

1. Atualize a configuração YAML do recurso do Config Connector e defina a anotação cnrm.cloud.google.com/deletion-policy como abandon.
2. Aplique a configuração YAML atualizada para atualizar a política de exclusão do recurso do Config Connector.
3. Abandone o recurso do Config Connector.
4. Atualize os campos imutáveis que precisam ser alterados na configuração YAML.
5. Aplique a configuração YAML atualizada para adquirir o recurso abandonado.

Resolver problemas por tipo

Use a tabela a seguir para resolver problemas com base no tipo de sintoma.

Tipo de problema	Problemas comuns
Conciliação	O recurso é atualizado a cada 5 a 15 minutos A reconciliação falha ou entra em loop devido a atualizações automáticas de campos O recurso não tem status KNV2005: o sincronizador está atualizando o recurso em excesso Recurso excluído pelo Config Connector Pod do controlador OOMKilled
Exclusão	Exclusões de namespaces travadas em Terminating Exclusões de recursos travadas em DeleteFailed após a exclusão do projeto
Permissões	Metadados do Compute Engine não definidos Erro 403: a solicitação não tem escopos de autenticação suficientes 403 Proibido: o autor da chamada não tem permissão Erro 403: o usuário não tem a permissão do IAM Erro de atualização com IAMPolicy, IAMPartialPolicy e IAMPolicyMember
Instalação e upgrades	Versão não compatível com instalações do complemento do Config Connector failed calling webhook PodSecurityPolicy impede upgrades
Configuração	Não é possível fazer mudanças em campos imutáveis Nenhuma correspondência para o tipo "RESOURCE_KIND" Os rótulos não são propagados para o Google Cloud recurso Erro devido a caracteres especiais no nome do recurso Não foi possível remover campos da especificação de recurso Valor inválido "merge" para a anotação state-into-spec

Reconciliação

A seção a seguir lista problemas comuns relacionados à reconciliação de recursos pelo Config Connector.

O recurso é atualizado a cada 5 a 15 minutos

Sintoma

O recurso do Config Connector muda do status UpToDate para Updating a cada 5 a 10 minutos.

Causa

É provável que o Config Connector esteja detectando diferenças não intencionais entre o estado desejado e o estado real do recurso, fazendo com que o Config Connector atualize constantemente o recurso.

Resolução

Primeiro, confirme se você não tem sistemas externos que modificam constantemente o Config Connector ou o recurso Google Cloud (por exemplo, pipelines de CI/CD, controladores personalizados, cron jobs etc.).

Se o comportamento não for devido a um sistema externo, verifique se Google Cloud está mudando algum dos valores especificados no recurso do Config Connector. Por exemplo, em alguns casos, o Google Cloud altera a formatação (por exemplo, capitalização) dos valores de campo, o que leva a uma diferença entre o estado desejado e o estado real do recurso.

Consiga o estado do recurso Google Cloud usando a API REST (por exemplo, para ContainerCluster) ou a Google Cloud CLI. Em seguida, compare esse estado com o recurso do Config Connector. Procure campos com valores que não correspondam e atualize o recurso do Config Connector para que correspondam. Procure valores que foram reformatados por Google Cloud. Por exemplo, consulte os problemas do GitHub #578 e #294.

Esse não é um método perfeito, já que os modelos de recursos do Config Connector e do Google Cloud são diferentes, mas ele permite detectar a maioria dos casos de diferenças não intencionais.

Se não for possível resolver o problema, consulte Ajuda adicional.

A reconciliação falha ou entra em loop devido a atualizações automáticas de campo

Esse problema ocorre quando o Google Cloud atualiza automaticamente um campo em um recurso que usa a anotação cnrm.cloud.google.com/state-into-spec: merge.

Sintoma

O recurso do Config Connector entra em um status UpdateFailed ou muda repetidamente para o status Updating depois que o Google Cloud atualiza automaticamente um campo que você não especificou no manifesto YAML.

Por exemplo, depois que o Cloud SQL realiza uma atualização de manutenção automática em um recurso SQLInstance, a reconciliação pode falhar com um erro semelhante a este:

Update call failed: error updating: patching SQLInstance ... maintenanceVersion failed: googleapi: Error 400: Invalid request: The requested maintenance version is not an available maintenance version to upgrade. Please refer to the availableMaintenanceVersions on the instance resource to see the available maintenance versions.., invalid

Causa

O recurso tem a anotação cnrm.cloud.google.com/state-into-spec: merge. Essa anotação era o padrão para recursos criados antes da versão 1.123.1 do Config Connector para CustomResourceDefinitions (CRDs) adicionadas na versão 1.113.0 e anteriores. Seu recurso também poderá ter essa anotação se o campo spec.stateIntoSpec estiver definido como Merge no recurso personalizado (CR) ConfigConnector ou ConfigConnectorContext.

Quando a anotação cnrm.cloud.google.com/state-into-spec é definida como merge, o Config Connector preenche campos não especificados, como o campo spec.maintenanceVersion, no campo spec do recurso do Kubernetes durante o reconciliamento inicial. Quando o Google Cloud atualiza automaticamente esse campo no recurso, o Config Connector trata o valor mais antigo armazenado no campo spec como o estado de destino e tenta reverter a mudança. Se a API Google Cloud rejeitar downgrades (como o Cloud SQL faz para o campo spec.maintenanceVersion), a reconciliação vai falhar.

Resolução

Para resolver esse problema, migre o recurso do comportamento Merge para o Absent para que o Config Connector pare de preencher campos não especificados no campo spec:

1. No manifesto YAML do recurso, omita o campo atualizado automaticamente (como o campo spec.maintenanceVersion) e defina a anotação cnrm.cloud.google.com/state-into-spec como absent.
2. Siga as etapas em Migrar recursos de Merge para Absent para abandonar o recurso do Kubernetes e adquiri-lo novamente com o manifesto YAML atualizado.

O recurso não tem status

Sintoma

Seus recursos não têm um campo status.

Causa

É provável que o Config Connector não esteja funcionando corretamente.

Resolução

Verifique se o Config Connector está em execução.

KNV2005: o sincronizador está atualizando o recurso em excesso

Sintoma

Você usa o Config Sync e está recebendo erros KNV2005 para recursos do Config Connector, semelhantes a este:

KNV2005: detected excessive object updates, approximately 6 times per
minute. This may indicate Config Sync is fighting with another controller over
the object.

Causa

É provável que o Config Sync e o Config Connector estejam competindo pelo recurso.

O Config Sync e o Config Connector estão "competindo" por um recurso se continuarem atualizando os mesmos campos com valores diferentes. A atualização de um aciona o outro para agir e atualizar o recurso, o que faz com que o outro aja e atualize o recurso, e isso se repete sem fim.

A luta não é um problema para a maioria dos campos. Os campos especificados no Config Sync não são alterados pelo Config Connector. Da mesma forma, os campos que não são especificados no Config Sync e que são padronizados pelo Config Connector são ignorados pelo Config Sync. Portanto, na maioria dos campos, o Config Sync e o Config Connector não precisam atualizar o mesmo campo.

Uma exceção são os campos de lista. Assim como o Config Connector pode definir subcampos padrão em campos de objeto, ele também pode definir subcampos padrão em objetos dentro de listas. No entanto, como os campos de lista nos recursos do Config Connector são atômicos, a definição de subcampos como padrão é considerada uma alteração completa do valor da lista.

Portanto, o Config Sync e o Config Connector vão "disputar" um recurso se o Config Sync definir um campo de lista e o Config Connector usar os valores padrão de todos os subcampos dessa lista.

Resolução

Para contornar esse problema, você tem as seguintes opções:

1. Atualize o manifesto do recurso no repositório do Config Sync para que corresponda ao que o Config Connector está tentando definir para o recurso.

   Uma maneira de fazer isso é interromper temporariamente a sincronização de configurações, aguardar o Config Connector terminar de reconciliar o recurso e atualizar o manifesto do recurso para que ele corresponda ao recurso no servidor da API Kubernetes.

2. Impeça que o Config Sync reaja a atualizações no recurso no servidor de API Kubernetes definindo a anotação client.lifecycle.config.k8s.io/mutation como ignore. Leia mais sobre como fazer o Config Sync ignorar mutações de objeto.

3. Impeça que o Config Connector atualize toda a especificação do recurso definindo a anotação cnrm.cloud.google.com/state-into-spec como absent no recurso. Essa anotação não é compatível com todos os recursos. Para ver se o recurso é compatível com a anotação, consulte a página de referência do recurso correspondente. Leia mais sobre a anotação.

Recurso excluído pelo Config Connector

Sintoma

Um recurso foi excluído do cluster, e você suspeita que o Config Connector o tenha excluído.

Causa

O Config Connector nunca exclui seus recursos sem uma causa externa. Por exemplo, executar kubectl delete, usar ferramentas de gestão de configuração, como o Argo CD, ou usar um cliente de API personalizado pode causar a exclusão de recursos.

Um equívoco comum é que o Config Connector iniciou e excluiu alguns dos recursos no cluster. Por exemplo, se você estiver usando o Config Connector, poderá notar solicitações de exclusão do gerenciador de controladores do Config Connector em relação a determinados recursos de mensagens de registro de contêiner ou registros de auditoria do cluster do Kubernetes. Essas solicitações de exclusão são resultado de gatilhos externos, e o Config Connector está tentando reconciliar as solicitações de exclusão.

Resolução

Para determinar por que um recurso foi excluído, é necessário analisar a primeira solicitação de exclusão enviada ao recurso correspondente. A melhor maneira de analisar isso é examinando os registros de auditoria do cluster do Kubernetes.

Por exemplo, se você estiver usando o GKE, poderá usar o Cloud Logging para consultar registros de auditoria do cluster do GKE. Por exemplo, se você quiser procurar as solicitações de exclusão iniciais de um recurso BigQueryDataset chamado my-dataset no namespace my-namespace, execute uma consulta como esta:

resource.type="k8s_cluster"
resource.labels.project_id="my-project-id"
resource.labels.cluster_name="my-cluster-name"
protoPayload.methodName="com.google.cloud.cnrm.bigquery.v1beta1.bigquerydatasets.delete"
protoPayload.resourceName="bigquery.cnrm.cloud.google.com/v1beta1/namespaces/my-namespace/bigquerydatasets/my-dataset"

Usando essa consulta, você procuraria a primeira solicitação de exclusão e, em seguida, verificaria authenticationInfo.principalEmail dessa mensagem de registro de exclusão para determinar a causa da exclusão.

Pod do controlador OOMKilled

Sintoma

Você vê um erro OOMKilled em um pod do controlador do Config Connector. O status do pod pode aparecer como OOMKilled ou Terminating.

Causa

Um contêiner ou todo o pod foi encerrado porque usou mais memória do que o permitido. Para verificar, execute o comando kubectl describe:

kubectl describe pod POD_NAME -n cnrm-system

Substitua POD_NAME pelo pod que você está resolvendo.

Além disso, analisar os logs de eventos do pod pode revelar ocorrências de eventos relacionados a OOM.

Resolução

Para resolver esse problema, use o recurso personalizado ControllerResource para aumentar a solicitação e o limite de memória do pod.

Exclusão

A seção a seguir lista problemas comuns relacionados a operações de exclusão iniciadas pelo usuário que podem causar conflitos com o Config Connector.

Exclusão de namespace travada em "Terminating"

Sintoma

A exclusão de um namespace está travada na etapa Terminating.

Causa

Esse problema pode ocorrer se o Config Connector estiver instalado no modo namespace e se o ConfigConnectorContext do namespace tiver sido excluído antes de todos os recursos do Config Connector nesse namespace. Quando o ConfigConnectorContext de um namespace é excluído, o Config Connector é desativado para esse namespace, o que impede que os recursos restantes do Config Connector nesse namespace sejam excluídos.

Resolução

Para corrigir esse problema, faça uma limpeza forçada e exclua manualmente os recursos Google Cloud subjacentes depois.

Para evitar esse problema no futuro, exclua apenas o ConfigConnectorContext depois que todos os recursos do Config Connector no namespace forem excluídos do Kubernetes. Evite excluir namespaces inteiros antes que todos os recursos do Config Connector nesse namespace tenham sido excluídos, já que o ConfigConnectorContext pode ser excluído primeiro.

A exclusão do recurso ficou travada em "DeleteFailed" após a exclusão do projeto

Sintoma

A exclusão de um recurso do Config Connector falha com o status DeleteFailed.

Causa

Esse problema pode acontecer se um projeto do Google Cloud for excluído antes do recurso.

Resolução

Para corrigir esse problema, restaure o projeto no Google Cloud para permitir que o Config Connector exclua os recursos filhos restantes do Kubernetes. Como alternativa, faça uma limpeza forçada.

Para evitar esse problema no futuro, exclua os projetos do Google Cloud somente depois que todos os recursos filhos do Config Connector forem excluídos do Kubernetes. Evite excluir namespaces inteiros que possam conter um recurso Project e os recursos filhos do Config Connector, já que o recurso Project pode ser excluído primeiro.

Permissões e autenticação

A seção a seguir lista problemas comuns relacionados a permissões e autenticação.

Metadados do Compute Engine não definidos

Sintoma

O recurso do Config Connector tem um status UpdateFailed com uma mensagem informando que os metadados do Compute Engine não estão definidos, semelhante ao erro a seguir:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
metadata: Compute Engine metadata "instance/service-accounts/default/token?
scopes=https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)compute%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSIN
G)auth%!F(MISSING)cloud-platform%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)cloud-identity%!C(MISSING)https%!A(MISSING)%!F(MISS
ING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)ndev.clouddns.readwrite%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSIN
G)devstorage.full_control%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)userinfo.email%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F
(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)drive.readonly" not
defined, detail:

Causa

É provável que a conta de serviço do IAM usada pelo Config Connector não exista.

Resolução

Para corrigir o problema, verifique se a conta de serviço do IAM usada pelo Config Connector existe.

Para evitar esse problema no futuro, siga as instruções de instalação do Config Connector.

Erro 403: a solicitação não tem escopos de autenticação suficientes

Sintoma

O recurso do Config Connector tem um status UpdateFailed com uma mensagem indicando um erro 403 devido a escopos de autenticação insuficientes, semelhante ao seguinte erro:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner-instance": googleapi: Error 403: Request had
insufficient authentication scopes.

Causa

A Federação de Identidade da Carga de Trabalho para GKE provavelmente não está ativada no cluster do GKE.

Para confirmar que a federação de identidade da carga de trabalho para GKE não está ativada, siga estas etapas:

1. Salve a seguinte configuração de pod como wi-test.yaml:

   apiVersion: v1
   kind: Pod
   metadata:
     name: workload-identity-test
     namespace: cnrm-system
   spec:
     containers:
     - image: google/cloud-sdk:slim
       name: workload-identity-test
       command: ["sleep","infinity"]
     serviceAccountName: cnrm-controller-manager
   

   Se você instalou o Config Connector usando o modo namespace, serviceAccountName precisa ser cnrm-controller-manager-NAMESPACE. Substitua NAMESPACE pelo namespace usado durante a instalação.

2. Crie o pod no cluster do GKE:

   kubectl apply -f wi-test.yaml
   

3. Abra uma sessão interativa no pod:

   kubectl exec -it workload-identity-test \
       --namespace cnrm-system \
       -- /bin/bash
   

4. Liste sua identidade:

   gcloud auth list
   

5. Verifique se a identidade listada corresponde à conta de serviço do Google vinculada aos seus recursos.

   Se você vir a conta de serviço padrão do Compute Engine, isso significa que a Federação de Identidade da Carga de Trabalho para GKE não está ativada no cluster do GKE e/ou no pool de nós.

6. Saia da sessão interativa e exclua o pod do cluster do GKE:

   kubectl delete pod workload-identity-test \
       --namespace cnrm-system
   

Resolução

Para corrigir esse problema, verifique se a federação de identidade da carga de trabalho para GKE está ativada no cluster.

Se o mesmo erro ainda aparecer, verifique se você também ativou a federação de identidade da carga de trabalho para GKE nos pools de nós do cluster.

403 Proibido: o autor da chamada não tem permissão

Sintoma

O recurso do Config Connector tem um status UpdateFailed com uma mensagem indicando um erro 403 devido à federação de identidade da carga de trabalho para GKE, semelhante ao seguinte erro:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
compute: Received 403 `Unable to generate access token; IAM returned 403
Forbidden: The caller does not have permission
This error could be caused by a missing IAM policy binding on the target IAM
service account.
For more information, refer to the Workload Identity documentation:
  https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#creating_a_relationship_between_ksas_and_gsas

Causa

A conta de serviço do Kubernetes do Config Connector não tem as permissões do IAM adequadas para representar sua conta de serviço do IAM como um usuário da Federação de Identidade da Carga de Trabalho para GKE.

Resolução

Para corrigir e mitigar o problema no futuro, consulte as instruções de instalação do Config Connector.

Erro 403: o autor da chamada não tem permissão do IAM

Sintoma

O recurso do Config Connector tem um status UpdateFailed com uma mensagem informando que o autor da chamada não tem uma permissão do IAM, semelhante ao seguinte erro:

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": googleapi: Error 403: Caller is missing IAM
permission spanner.instances.get on resource
projects/my-project/instances/my-spanner-instance., detail:

Causa

A conta de serviço do IAM usada pelo Config Connector não tem a permissão do IAM indicada na mensagem, que é necessária para gerenciar o recurso Google Cloud .

Resolução

Se o mesmo erro persistir depois de conceder à sua conta de serviço do IAM as permissões adequadas, verifique se o recurso está sendo criado no projeto correto. Verifique o campo spec.projectRef do recurso do Config Connector (ou a anotação cnrm.cloud.google.com/project-id se o recurso não for compatível com um campo spec.projectRef) e confira se ele está referenciando o projeto correto. O Config Connector usa o nome do namespace como o ID do projeto se nem o recurso nem o namespace especificarem um projeto de destino. Leia mais sobre como configurar o projeto de destino para recursos no escopo do projeto.

Se o mesmo erro ainda aparecer, verifique se a Federação de Identidade da Carga de Trabalho para GKE está ativada no cluster do GKE.

Para evitar esse problema no futuro, siga as instruções de instalação do Config Connector.

Erro de atualização com IAMPolicy, IAMPartialPolicy e IAMPolicyMember

Sintoma

Você vai ver um status UpdateFailed com uma mensagem de erro indicando um erro 400 porque a conta de serviço não existe:

Update call failed: error setting policy member: error applying changes: summary: Request `Create IAM Members roles/[MYROLE] serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com for project \"projects/[PROJECT_ID]\"` returned error: Error applying IAM policy for project \"projects/[PROJECT_ID]\": Error setting IAM policy for project \"projects/[PROJECT_ID]\": googleapi: Error 400: Service account [NAME]@[PROJECT_ID].iam.gserviceaccount.com does not exist., badRequest

Causa

Se você excluir um recurso IAMServiceAccount do Config Connector antes de limpar os recursos IAMPolicy, IAMPartialPolicy e IAMPolicyMember que dependem dessa conta de serviço, o Config Connector não poderá localizar a conta de serviço referenciada nesses recursos do IAM durante a reconciliação.

Resolução

Para resolver esse problema, verifique suas contas de serviço e confira se a conta de serviço necessária para esses recursos do IAM foi excluída. Se a conta de serviço for excluída, limpe também os recursos relacionados do Config Connector do IAM. Para IAMPolicyMember, exclua todo o recurso. Para IAMPolicy e IAMParitialPolicy, remova apenas as vinculações que envolvem a conta de serviço excluída. No entanto, essa limpeza não remove as vinculações de papel doGoogle Cloud imediatamente. As vinculações de papel do Google Cloud são retidas por 60 dias devido à retenção na conta de serviço excluída. Para mais informações, consulte a Google Cloud documentação do IAM sobre Excluir uma conta de serviço.

Observação: se você tiver problemas durante a exclusão, talvez seja necessário fazer uma limpeza forçada. Se você quiser excluir as vinculações do IAM de Google Cloud imediatamente, exclua manualmente os recursos Google Cloud subjacentes usando gcloud.

Para evitar esse problema, sempre limpe os recursos IAMPolicy, IAMPartialPolicy e IAMPolicyMember do Config Connector antes de excluir o IAMServiceAccount referenciado.

O recurso ServiceIdentity falha com Invalid service producer

Sintoma

O recurso ServiceIdentity tem um status UpdateFailed, com uma mensagem de erro semelhante a esta:

Update call failed: error applying desired state: summary: Error creating Service Identity: Invalid service producer: ...

Causa

Esse erro significa que o recurso especificado não é compatível com a criação de identidade de serviço sob demanda.

Resolução

O recurso ServiceIdentity pode gerar identidades de serviço apenas para serviços compatíveis. Para verificar se um serviço é compatível com a criação de identidade de serviço on demand antes de aplicar sua configuração, execute o seguinte comando:

gcloud beta services identity create --service SERVICE_NAME.googleapis.com

Substitua SERVICE_NAME pelo nome do serviço, por exemplo, spanner.

Se o comando for bem-sucedido, o Config Connector poderá criar uma identidade para esse serviço. Se o comando falhar, isso significa que o Config Connector não pode criar uma identidade para esse serviço.

Instalação e upgrades

A seção a seguir lista problemas comuns relacionados à instalação ou ao upgrade da versão do Config Connector.

Versão não compatível com instalações do complemento do Config Connector

Sintoma

Se não for possível ativar o complemento Config Connector, a seguinte mensagem de erro será exibida: Node version 1.15.x-gke.x s unsupported.

A mensagem de erro também aparece se a Federação de identidade da carga de trabalho para GKE ou o GKE Monitoring estiverem desativados.

Causa

A versão do cluster do GKE não atende aos requisitos ou os recursos necessários estão desativados.

Resolução

Para resolver esse erro, verifique se a versão do cluster do GKE atende aos requisitos de versão e recurso. Verifique se a Federação de Identidade da Carga de Trabalho para GKE e o GKE Monitoring estão ativados.

Para ver todas as versões válidas para os clusters, execute o comando a seguir.

gcloud container get-server-config --format "yaml(validMasterVersions)" \
    --zone ZONE

Substitua ZONE pela zona do Compute Engine.

Escolha na lista uma versão que atenda aos requisitos.

failed calling webhook

Sintoma

Não é possível desinstalar o Config Connector e você recebe um erro semelhante ao seguinte:

error during reconciliation: error building deployment objects: error finalizing the deletion of Config Connector system components deployed by ConfigConnector controller: error waiting for CRDs to be deleted: error deleting CRD accesscontextmanageraccesslevels.accesscontextmanager.cnrm.cloud.google.com: Internal error occurred: failed calling webhook "abandon-on-uninstall.cnrm.cloud.google.com": failed to call webhook: Post "https://abandon-on-uninstall.cnrm-system.svc:443/abandon-on-uninstall?timeout=3s": service "abandon-on-uninstall" not found

Causa

Esse problema pode ocorrer ao usar o complemento do Config Connector e desativar o Config Connector antes de remover os CRDs do Config Connector.

Resolução

Para resolver esse erro, primeiro exclua manualmente os webhooks:

kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true

Em seguida, desinstale o Config Connector.

PodSecurityPolicy impede upgrades

Sintoma

Depois de mudar do complemento do Config Connector para uma instalação manual e fazer upgrade do Config Connector para uma nova versão, os pods cnrm não são atualizados.

Causa

O uso de PodSecurityPolicies pode impedir a atualização de pods cnrm.

Para confirmar se as PodSecurityPolicies estão impedindo o upgrade, verifique os eventos do config-connector-operator e procure um erro semelhante ao seguinte:

create Pod configconnector-operator-0 in StatefulSet configconnector-operator failed error: pods "configconnector-operator-0" is forbidden: PodSecurityPolicy: unable to admit pod: [pod.metadata.annotations[seccomp.security.alpha.kubernetes.io/pod]: Forbidden: seccomp may not be set pod.metadata.annotations[container.seccomp.security.alpha.kubernetes.io/manager]: Forbidden: seccomp may not be set]

Resolução

Para resolver esse problema, é preciso especificar a anotação na PodSecurityPolicy que corresponde à anotação mencionada no erro. No exemplo anterior, a anotação é seccomp.security.alpha.kubernetes.io.

Configuração

A seção a seguir lista problemas comuns relacionados à configuração de recursos.

Não é possível fazer mudanças em campos imutáveis

O Config Connector rejeita atualizações em campos imutáveis na admissão.

Por exemplo, atualizar um campo imutável com kubectl apply faz com que o comando falhe imediatamente.

Isso significa que ferramentas que reaplicam recursos continuamente (por exemplo, GitOps) podem ficar presas ao atualizar um recurso se não processarem erros de admissão.

Como o Config Connector não permite atualizações em campos imutáveis, a única maneira de fazer isso é excluir e recriar o recurso.

Erro ao atualizar os campos imutáveis quando não há atualização

Talvez você veja os seguintes erros no status do recurso do Config Connector logo após criar ou adquirir um recurso do Google Cloud usando o Config Connector:

• Update call failed: error applying desired state: infeasible update: ({true \<nil\>}) would require recreation (exemplo)

• Update call failed: cannot make changes to immutable field(s) (exemplo)

Isso não significa que você atualizou o recurso, mas que a API Google Cloud fez uma mudança em um campo imutável gerenciado por você no recurso do Config Connector. Isso causou a incompatibilidade entre o estado desejado e o estado ativo dos campos imutáveis.

Para resolver o problema, atualize os valores desses campos imutáveis no recurso do Config Connector para que correspondam ao estado ativo. Para isso, siga as etapas abaixo:

1. Atualize a configuração YAML do recurso do Config Connector e defina a anotação cnrm.cloud.google.com/deletion-policy como abandon.
2. Aplique a configuração YAML atualizada para atualizar a política de exclusão do recurso do Config Connector.
3. Abandone o recurso do Config Connector.
4. Imprima o estado ativo do recurso Google Cloud correspondente usando a CLI gcloud.
5. Encontre a incompatibilidade entre a saída da CLI gcloud e a configuração YAML do recurso do Config Connector e atualize esses campos na configuração YAML.
6. Aplique a configuração YAML atualizada para adquirir o recurso abandonado.

Nenhuma correspondência para o tipo "RESOURCE_KIND"

Sintoma

Você verá o erro No matches for kind "RESOURCE_KIND".

Causa

O cluster do Kubernetes não tem o CRD para o tipo de recurso RESOURCE_KIND instalado.

Resolução

Verifique se o tipo é um tipo de recurso compatível com o Config Connector.

Se o tipo for compatível, isso significa que a instalação do Config Connector está desatualizada ou inválida.

Se você instalou o Config Connector usando o complemento do GKE, a instalação será atualizada automaticamente. Se você instalou o Config Connector manualmente, faça um upgrade manual.

Verifique o repositório do GitHub para determinar quais tipos de recursos são compatíveis com quais versões do Config Connector (por exemplo, estes são os tipos compatíveis com o Config Connector v1.44.0).

Os rótulos não são propagados para o recurso Google Cloud

Sintoma

Os rótulos no YAML não estão aparecendo no recurso Google Cloud .

Causa

Nem todos os recursos do Google Cloud aceitam rótulos.

Resolução

O Config Connector propaga os rótulos encontrados em metadata.labels para o recursoGoogle Cloud subjacente. Confira a documentação da API REST do recurso (por exemplo, documentação da API para PubSubTopic) para saber se ele é compatível com rótulos.

Erro devido a caracteres especiais no nome do recurso

Sintoma

Você vê um erro relacionado a caracteres inválidos em metadata.name:

a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

Causa

Caracteres especiais não são válidos no campo metadata.name do Kubernetes.

Resolução

Se você quiser dar ao recurso um nome que não seja válido no Kubernetes, mas que seja um nome de recurso válido do Google Cloud , use o campo resourceID, conforme mostrado no exemplo a seguir:

apiVersion: sql.cnrm.cloud.google.com/v1beta1
kind: SQLUser
metadata:
  name: 'test'
spec:
  instanceRef:
    name: sqlinstance-sample-postgresql
  host: "%"
  type: CLOUD_IAM_USER
  resourceID: [e-mail]

Essa configuração faz com que o Config Connector use resourceID em vez de metadata.name como o nome do recurso.

Não foi possível remover campos da especificação do recurso

Sintoma

Remover um campo da especificação de um recurso do Config Connector não o remove do recurso.

Causa

Remover um campo da especificação de um recurso gerenciado pelo Config Connector não deixa esse campo vazio nem o reverte para um valor padrão. Em vez disso, ele faz com que esse campo seja gerenciado externamente.

Observação: há uma exceção: campos dentro de listas. As listas são atômicas, o que significa que o Config Connector tentará definir a lista no Google Cloud subjacente para ser equivalente à especificada na especificação.

Resolução

Se você quiser alterar o valor de um campo para vazio ou padrão no recursoGoogle Cloud subjacente, zere o campo na especificação do recurso do Config Connector:

• Para o campo do tipo de lista, defina o campo como uma lista vazia usando [].

  O exemplo a seguir mostra o campo targetServiceAccounts que queremos remover:

  spec:
    targetServiceAccounts:
      - external: "[e-mail]"
      - external: "[e-mail]"
  

  Para remover esse campo, defina o valor como vazio:

  spec:
    targetServiceAccounts: []
  

• Para um campo de tipo primitivo, defina o campo como vazio usando uma das seguintes opções:

  Tipo	Valor vazio
  string	""
  bool	"false"
  integer	0

  O exemplo a seguir mostra o campo identityNamespace que queremos remover:

  spec:
    workloadIdentityConfig:
      identityNamespace: "example-project.svc.id.goog"
  

  Para remover esse campo, defina o valor como vazio:

  spec:
    workloadIdentityConfig:
      identityNamespace: ""
  

• Para campos do tipo objeto, tente definir os subcampos do tipo objeto como vazios ou padrão seguindo as orientações da seção anterior e verifique se funciona. No entanto, não há garantia de que isso funcione.

Valor "merge" inválido para a anotação state-into-spec

Esse problema ocorre quando um recurso usa a anotação cnrm.cloud.google.com/state-into-spec: merge, mas o tipo de recurso ou a versão do Config Connector rejeita o valor merge.

Sintoma

O recurso do Config Connector não é reconciliado com uma mensagem de erro semelhante a esta:

Update call failed: error applying desired state: invalid value "merge" for "cnrm.cloud.google.com/state-into-spec" annotation

Causa

Esse erro ocorre por um dos seguintes motivos:

• O tipo de recurso não é compatível com o comportamento Merge, mas tem a anotação cnrm.cloud.google.com/state-into-spec: merge. Essa anotação pode ser definida diretamente no recurso ou herdada da configuração spec.stateIntoSpec: Merge no CR ConfigConnector ou ConfigConnectorContext. Os CRDs adicionados no Config Connector versão 1.114.0 e posteriores são compatíveis apenas com o comportamento Absent.
• Você fez upgrade para a versão 1.134.0 ou 1.134.1 do Config Connector e tem um recurso SQLInstance que tinha a anotação cnrm.cloud.google.com/state-into-spec: merge por padrão de uma versão anterior. As versões 1.134.0 e 1.134.1 tinham um problema conhecido que rejeitava o valor merge em recursos SQLInstance.

Resolução

Para resolver esse problema, siga as etapas que se aplicam ao seu cenário:

• O tipo de recurso não é compatível com o comportamento Merge: defina a anotação cnrm.cloud.google.com/state-into-spec: absent no manifesto YAML do recurso e defina o campo spec.stateIntoSpec como Absent no CR ConfigConnector ou ConfigConnectorContext. Para verificar se o tipo de recurso é compatível com o comportamento Merge, consulte Tipos com suporte a Merge. Se a anotação já estiver presente em um recurso no cluster, siga as etapas em Migrar recursos de Merge para Absent.
• Você usa um recurso SQLInstance na versão 1.134.0 ou 1.134.1 do Config Connector: faça upgrade do Config Connector para a versão 1.134.2 ou mais recente. Como alternativa, migre o recurso SQLInstance para a anotação cnrm.cloud.google.com/state-into-spec: absent seguindo as etapas em Migrar recursos de Merge para Absent.

O Config Connector não inicia em nós baseados em Arm

Se o cluster tiver pools de nós que usam a arquitetura Arm (como as séries de máquinas C4A, N4A ou Tau T2A), talvez os componentes do Config Connector não sejam executados. Essa é uma limitação conhecida porque o Config Connector não é compatível com sistemas baseados em Arm.

Sintomas

Se a instância do Config Connector for afetada por esse problema, talvez você tenha os seguintes sintomas:

• Os pods no namespace cnrm-system permanecem no estado Pending.
• Os pods podem mostrar um CrashLoopBackOff com uma mensagem de erro nos registros semelhante a: exec user process caused "exec format error".
• A descrição do pod revela falhas de programação ou incompatibilidades de arquitetura.

Resolução

Para resolver esse problema, verifique se os componentes do Config Connector estão programados em nós com arquitetura x86:

• Adicione um pool de nós x86: se o cluster tiver apenas nós Arm, adicione pelo menos um pool de nós usando um tipo de máquina x86 (como e2-standard-2) para hospedar os pods do controlador do Config Connector.
• Verifique os taints de nós: os nós do GKE Arm geralmente são taintados com kubernetes.io/arch=arm64:NoSchedule para evitar que cargas de trabalho exclusivas de x86 sejam programadas neles. Verifique se você não adicionou tolerâncias às implantações do Config Connector que permitiriam a execução nesses nós.

Limpeza forçada

Se os recursos do Config Connector estiverem presos na exclusão e você quiser se livrar deles do cluster do Kubernetes, force a exclusão excluindo os finalizadores.

Aviso: essa operação deve ser feita como último recurso, já que as exclusões de finalizadores estão fora dos limites do uso normal do Config Connector e podem ter consequências indesejadas. Em especial, não há garantias sobre o que acontece com os recursos Google Cloud subjacentes.

É possível excluir os finalizadores de um recurso editando-o com kubectl edit, excluindo o campo metadata.finalizers e salvando o arquivo para preservar as alterações no servidor de API Kubernetes.

Como a exclusão dos finalizadores de um recurso permite que ele seja excluído imediatamente do cluster do Kubernetes, o Config Connector pode (mas não necessariamente) não ter a chance de concluir a exclusão do recursoGoogle Cloud subjacente. Isso significa que talvez você queira excluir manualmente os recursos do Google Cloud depois.

Monitoramento

Ao monitorar o Config Connector e analisar os registros dele, é possível determinar a origem dos problemas e entender melhor comportamentos inesperados.

Métricas

É possível usar o Prometheus para coletar e mostrar métricas do Config Connector.

Logging

Todos os pods do Config Connector geram registros estruturados no formato JSON.

Os registros dos pods do controlador são particularmente úteis para depurar problemas com a reconciliação de recursos.

É possível consultar registros de recursos específicos filtrando os seguintes campos nas mensagens de registro:

• logger: contém o tipo do recurso em letras minúsculas. Por exemplo, os recursos PubSubTopic têm um logger de pubsubtopic-controller.
• resource.namespace: contém o namespace do recurso.
• resource.name: contém o nome do recurso.

Como usar o Logging para consultas avançadas de registros

Se você estiver usando o GKE, use o Cloud Logging para consultar registros de um recurso específico com a seguinte consulta:

Observação: a sintaxe de consulta não é compatível com comentários. A consulta a seguir usa uma convenção de comentários, # comment, para fornecer texto explicativo, mas esses comentários não podem ser incluídos em consultas.

# Filter to include only logs coming from the controller Pods
resource.type="k8s_container"
resource.labels.container_name="manager"
resource.labels.namespace_name="cnrm-system"
labels.k8s-pod/cnrm_cloud_google_com/component="cnrm-controller-manager"

# Filter to include only logs coming from a particular GKE cluster
resource.labels.cluster_name="GKE_CLUSTER_NAME"
resource.labels.location="GKE_CLUSTER_LOCATION"

# Filter to include only logs for a particular Config Connector resource
jsonPayload.logger="RESOURCE_KIND-controller"
jsonPayload.resource.namespace="RESOURCE_NAMESPACE"
jsonPayload.resource.name="RESOURCE_NAME"

Substitua:

• GKE_CLUSTER_NAME pelo nome do cluster do GKE que executa o Config Connector.
• GKE_CLUSTER_LOCATION pelo local do cluster do GKE que executa o Config Connector. Por exemplo, us-central1.
• RESOURCE_KIND pelo tipo do recurso em letras minúsculas. Por exemplo, pubsubtopic.
• RESOURCE_NAMESPACE pelo namespace do recurso.
• RESOURCE_NAME com o nome do recurso.

Mais ajuda

Para receber mais ajuda, registre um problema no GitHub ou entre em contato com o suporte doGoogle Cloud .