Tipos de controlador do Config Connector

O Config Connector usa uma arquitetura em camadas para reconciliar recursos no Google Cloud ambiente com as especificações do Kubernetes. Um controlador pai de nível superior encaminha a reconciliação de cada recurso para uma das quatro implementações de controlador subjacentes.

Entender cada tipo de controlador, como eles diferem tecnicamente e como você pode controlar o roteamento em todo o namespace pode ajudar a otimizar o desempenho e solucionar problemas de configuração.

Tipos de controlador subjacentes

O Config Connector usa os seguintes tipos de controlador:

  • Controladores diretos: esse controlador usa a biblioteca padrão do Kubernetes controller-runtime e se comunica com as Google Cloud APIs diretamente usando os SDKs oficiais do Google Cloud Go. Recomendamos o uso de controladores diretos sempre que possível. Nem todos os recursos oferecem suporte ao controlador direto. Novos recursos usam o controlador direto por padrão. Os recursos atuais são migrados regularmente. Para mais informações, consulte as notas de lançamento.
  • Controladores baseados no Terraform (TF) : esse controlador atua como um "wrapper" para o provedor do Google do Terraform. O controlador traduz as especificações do Modelo de Recursos do Kubernetes (KRM, na sigla em inglês) em estados compatíveis com o Terraform e implementa as operações plan e apply do Terraform.
  • Controladores baseados em DCL:esse tipo de controlador atua como um "wrapper" para a Google Cloud biblioteca de cliente declarativa (DCL, na sigla em inglês).
  • Controladores específicos do IAM:são controladores especializados projetados especificamente para gerenciar recursos do Identity and Access Management (IAM), incluindo IAMPolicy, IAMPartialPolicy, IAMPolicyMember e IAMAuditConfig. Alguns recursos do IAM oferecem suporte opcional ao controlador direto.

Benefícios dos controladores diretos

Alguns tipos de recursos oferecem suporte a vários tipos de controlador. Se um recurso oferecer suporte ao controlador direto, recomendamos o uso dele em vez de outro tipo de controlador pelos seguintes motivos:

  • Consumo reduzido de recursos:os controladores diretos não têm a sobrecarga de CPU e memória associada à execução e tradução de estados baseados no Terraform ou em DCL.
  • Latência de reconciliação aprimorada: os controladores diretos podem fazer operações diretas em endpoints, reduzindo o tempo médio necessário para alcançar a consistência do estado do recurso. Google Cloud
  • Status granular e diferenças estruturadas:o controlador direto fornece relatórios de diferenças estruturadas nos registros cnrm-controller-manager. Esses registros contêm as mudanças de campo precisas que iniciaram erros, como loops de reconciliação, o que pode facilitar a solução de problemas.
  • Estado observado nativo: os controladores diretos preenchem status.observedState no status do recurso, fornecendo uma visualização transparente do lado do servidor dos campos de recursos retornados diretamente pelas Google Cloud APIs.
  • Melhor gerenciamento do ciclo de vida:os controladores diretos incluem outros recursos, como a exclusão de órfãos.

Controlador de roteamento pai

Independentemente do tipo de recurso, o Config Connector intercepta todas as solicitações de reconciliação em um controlador pai central. O controlador pai atua como um roteador, avaliando qual lógica filha processa a sincronização ativa usando as seguintes regras de precedência:

  1. Substituições de namespace:o controlador pai primeiro verifica a configuração do recurso ConfigConnectorContext no namespace do recurso de destino para detectar substituições explícitas do controlador.
  2. Padrões estáticos:se nenhuma substituição local for especificada, o controlador pai será definido como o reconciliador de tempo de build definido na configuração de mapeamento estático do Config Connector.

Identificar o controlador de um recurso

É possível determinar qual tipo de controlador está configurado ou ativo para um recurso específico Google Cloud usando o mapeamento de código ativo ou examinando as estruturas CustomResourceDefinition (CRD) no Google Kubernetes Engine (GKE).

Para pesquisar a configuração estática de um recurso, inspecione o recurso no GitHub em pkg/controller/resourceconfig/static_config.go e procure o bloco de configuração do recurso, como no exemplo a seguir:

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController:indica o reconciliador padrão usado se nenhuma regra de substituição de contexto no nível do namespace for especificada.
  • SupportedControllers:lista todos os reconciliadores implementados e disponíveis para esse recurso. As substituições mudam para os reconciliadores listados aqui.

Para inspecionar rótulos de CRD, use o comando kubectl get crd:

kubectl get crd RESOURCE_NAME -o jsonpath='{.metadata.labels}'

Substitua RESOURCE_NAME pelo nome exato do CRD do Config Connector, por exemplo, bigquerydatasets.bigquery.cnrm.cloud.google.com.

Verifique os resultados das seguintes informações:

  • cnrm.cloud.google.com/tf2crd: "true": o controlador baseado no Terraform (TF) gerencia o recurso.
  • cnrm.cloud.google.com/dcl2crd: "true": o controlador baseado em DCL gerencia o recurso.
  • Ausência desses rótulos:o controlador direto gerencia o recurso.

Substituir o controlador padrão

Há dois métodos principais para substituir o tipo de controlador no Config Connector. A distinção entre eles envolve principalmente o escopo operacional, a sobrecarga de manutenção e a precedência que eles assumem durante a reconciliação.

A tabela a seguir resume as diferenças entre as duas abordagens:

Recurso Anotação de recurso Substituição do ConfigConnectorContext
Escopo Instância de recurso único Todos os recursos de um tipo em um namespace
Precedência Mais alta (substitui o ConfigConnectorContext) Média (substitui o padrão estático)
Recomendado? Não Sim
Ideal para Teste único Implantação em toda a equipe ou projeto

Substituir o controlador de um recurso específico

É possível forçar uma instância de recurso específica a ser executada com um reconciliador específico adicionando a anotação alpha.cnrm.cloud.google.com/reconciler aos metadados do recurso. Embora essa abordagem não seja recomendada pelos motivos especificados na seção anterior, talvez seja necessário testar configurações para uma única instância de recurso ou para manter configurações legadas.

apiVersion: bigquery.cnrm.cloud.google.com/v1beta1
kind: BigQueryDataset
metadata:
  name: my-bq-ds
  namespace: NAMESPACE_NAME
  annotations:
    alpha.cnrm.cloud.google.com/reconciler: direct
spec:
  ...

Os valores aceitos para a anotação são direct, tf ou dcl.

Substituir o controlador de um namespace

Para configurar uma substituição em todo o namespace usando o recurso personalizado ConfigConnectorContext, siga estas etapas:

  1. Recupere o nome e o grupo das definições de recursos. Por exemplo, para o recurso BigQueryDataset, o tipo de recurso é BigQueryDataset e o grupo é bigquery.cnrm.cloud.google.com.

  2. Edite o objeto ConfigConnectorContext dentro do namespace que contém os recursos gerenciados:

    kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME

    Substitua NAMESPACE_NAME pelo namespace de destino.

  3. Adicione as substituições de destino. Por exemplo, para substituir todas as instâncias BigQueryDataset nesse namespace para serem executadas com o controlador direto, defina a configuração da seguinte maneira:

    apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: NAMESPACE_NAME
spec:
  googleServiceAccount: "kcc-sa@my-project.iam.gserviceaccount.com"
  experiments:
    controllerOverrides:
      BigQueryDataset.bigquery.cnrm.cloud.google.com: direct

  4. Salve e aplique o recurso. O controlador pai aplica automaticamente as novas regras de roteamento do reconciliador direto de forma dinâmica a todos os recursos correspondentes nesse namespace.

Restrições e casos de uso de substituição de namespace

  • Requisito de suporte explícito:para que uma substituição seja bem-sucedida, o tipo de controlador de destino precisa ser implementado para o tipo de recurso. Para verificar se um tipo de controlador é aceito, consulte Identificar o controlador de um recurso. Se o tipo de controlador especificado na substituição não for aceito, o controlador pai vai ignorar a substituição e o reconciliador padrão continuará processando o recurso.
  • Limite de namespace:as substituições em um ConfigConnectorContext são aplicadas coletivamente a todas as instâncias desse tipo de recurso que residem nesse namespace específico. Não é possível segmentar instâncias de recursos individuais com substituições no escopo do namespace.
  • Controle de acesso:a atualização de um objeto ConfigConnectorContext geralmente exige privilégios de equipe de plataforma de nível superior em comparação com edições de recursos padrão.
  • Relatório de status de substituição:se um tipo de controlador inválido ou não aceito for especificado nas substituições ConfigConnectorContext, o controlador pai vai marcar o contexto como não íntegro. Para verificar isso, execute kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml e verifique os campos .status.healthy e .status.errors.
  • Quando usar:essa é a abordagem recomendada para substituir controladores. Use-o para ativar namespaces inteiros para controladores modernos (como diretos) ou para aplicar consistência arquitetônica em um projeto.