Configurar o LocalDNS no Serviço Kubernetes do Azure (AKS)

Aplica-se a: ✔️ AKS Automatic ✔️ AKS Standard

Para a maioria das cargas de trabalho de produção, o AKS Automatic é a opção predefinida pronta para produção recomendada para o AKS. O LocalDNS está pré-configurado em clusters automáticos do AKS. No AKS Standard, o comportamento do LocalDNS depende da versão do Kubernetes e do perfil LocalDNS existente do pool de nós.

O LocalDNS é uma funcionalidade no AKS que melhora a resolução, desempenho e resiliência do DNS para cargas de trabalho a correr no seu cluster. Ao executar um proxy DNS em cada nó, o LocalDNS reduz a latência das consultas DNS, melhora a fiabilidade durante interrupções transitórias da rede e fornece controlos avançados de cache e encaminhamento quando precisa de personalização.

Para saber o que é o LocalDNS, incluindo detalhes da arquitetura e capacidades chave, consulte Resolução DNS no Azure Kubernetes Service (AKS).

Comportamento do AKS Automatic e do AKS Standard LocalDNS

Verificações de compatibilidade para o modo Preferred

A partir do Kubernetes 1.37, o AKS Standard atribui Preferred modo a pools de nós elegíveis sem um perfil LocalDNS explícito quando esses pools são criados ou atualizados. O AKS preserva perfis explicitamente configurados.

Antes de ativar inicialmente o LocalDNS no Preferred modo, o AKS verifica os seguintes requisitos de compatibilidade. Se um requisito não for cumprido, o LocalDNS permanece desativado.

Assim que o AKS ativa o LocalDNS no modo Preferred, o LocalDNS permanece ativado durante atualizações subsequentes não relacionadas do conjunto de nós. Para o desativar, defina explicitamente o LocalDNS mode para Disabled.

Práticas recomendadas para configuração LocalDNS

Ao implementar o LocalDNS em seus clusters AKS, considere as seguintes práticas recomendadas:

• Comece com uma configuração mínima: Comece com uma configuração simples que use o Preferred modo para validar a sintaxe da sua configuração LocalDNS antes de passar para o Required modo. O Preferred modo valida a sua configuração sem ativar o LocalDNS, permitindo-lhe detetar erros de configuração cedo sem afetar o cluster.
• Implemente estratégias adequadas de cache: Configure as definições de cache com base nas características da sua carga de trabalho:
  • Para alterar registros com frequência, use valores mais curtos cacheDurationInSeconds . Ao fazer isso, é importante observar que cacheDurationInSeconds atua como um limite no TTL do registro DNS, mas não o aumenta. O TTL resultante é o menor do que é retornado do upstream ou do que é definido no plug-in de cache.
  • Para registros estáveis, use durações de cache mais longas para reduzir consultas DNS.
  • Habilite serveStale com as configurações apropriadas para manter o serviço durante interrupções de DNS.
  • O cache com LocalDNS opera com base no melhor esforço e não garante respostas obsoletas. O cache é dividido em 256 fragmentos e com um máximo padrão de 10.000 entradas, permitindo que cada fragmento contenha cerca de 39 entradas. Quando um fragmento está cheio e uma nova entrada precisa ser adicionada, uma das entradas existentes é escolhida aleatoriamente para ser removida. Não há preferência por entradas mais antigas ou que expiram. Como resultado, um registro obsoleto pode nem sempre estar disponível, especialmente em alto volume de consultas.
• Monitorizar o desempenho do DNS: Após ativar o LocalDNS, monitorize o desempenho do DNS da sua aplicação utilizando:
  • Métricas de desempenho de aplicativos.
  • Métricas de nó para detetar uma pressão reduzida na rede.
  • Registrar entradas quando queryLogging estiver definido como Log.
• Siga o princípio de menor privilégio: Ao configurar regras de encaminhamento DNS, permita apenas o acesso aos servidores e domínios DNS necessários.
• Teste antes da implementação em produção: Teste sempre a configuração do LocalDNS num ambiente não de produção antes de a implementar em clusters de produção.
• Usar infraestrutura como código (IaC): armazene seu arquivo localdnsconfig.json em seu repositório de infraestrutura e inclua-o em seus modelos de implantação AKS.
• Configuração de rede para encaminhamento TCP: Ao usar TCP para encaminhamento DNS para VnetDNS, certifique-se de que seus NSGs (Network Security Groups), firewalls ou Network Virtual Appliances (NVAs) não bloqueiem o tráfego TCP entre os servidores CoreDNS/LocalDNS e VnetDNS.
• Evite habilitar o NodeLocal DNSCache e o LocalDNS: não é recomendado habilitar o NodeLocal DNSCache e o LocalDNS upstream do Kubernetes no pool de nós. Embora o AKS não bloqueie esta configuração, todo o tráfego DNS é encaminhado através do LocalDNS, o que pode levar a comportamentos inesperados ou a benefícios reduzidos do NodeLocal DNSCache.
• Não imponha um limite de ligação TCP ao servidor DNS personalizado a montante antes de ativar o LocalDNS: Quando ativa o LocalDNS num pool de nós, cada nó abre ligações TCP de longa duração do seu proxy DNS local para o resolvedor a montante, em vez das trocas UDP curtas usadas anteriormente. Se o seu servidor DNS personalizado (como BIND, Unbound, Windows DNS ou um dispositivo de terceiros) estiver configurado com um limite fixo para ligações TCP concorrentes, ou se ajustou esse limite com base no tráfego pré-LocalDNS, as novas ligações TCP do LocalDNS podem ser rejeitadas, causando falhas na resolução DNS em todo o cluster. Deixe qualquer limite de ligações TCP no valor predefinido, suficientemente elevado, antes de ativar o LocalDNS, valide a contagem de ligações TCP em regime estável dos seus nós do AKS após a ativação e só depois ajuste o limite, deixando margem para a expansão dos nós, atualizações e recriação das imagens.

Pré-requisitos

Clusters automáticos do AKS incluem o LocalDNS pré-configurado. Os pré-requisitos desta secção aplicam-se principalmente quando se ativa ou se personaliza o comportamento do LocalDNS, o que é mais comum em cenários de personalização AKS Standard e avançados.

• Deve ter um cluster AKS existente com Kubernetes versões 1.31 e posteriores para usar o LocalDNS. Se precisares de um cluster AKS, podes criar um usando CLI do Azure, Azure PowerShell, ou o portal Azure.
• Este artigo requer a versão 2.80.0 do CLI do Azure e posteriores. Se estiveres a usar o Azure Cloud Shell, a versão mais recente já está instalada.
• O LocalDNS é apenas suportado em pools de nós a executar Azure Linux ou Ubuntu 22.04 ou mais recentes.
• A SKU de máquina virtual (VM) usada para seu pool de nós deve ter pelo menos 4 vCPUs (núcleos) para suportar LocalDNS.

Ativar ou personalizar o LocalDNS num cluster AKS

Configuras o LocalDNS ao nível do pool de nós no AKS, para poderes adaptar o comportamento por carga de trabalho e ambiente.

No AKS Automatic, o LocalDNS já está pré-configurado, por isso esta secção é principalmente para personalização.

No AKS Standard, utilize esta secção para ativar e configurar o LocalDNS.

Valide DNS personalizado antes de ativar o LocalDNS

Se a sua rede virtual usar servidores DNS personalizados, teste ambos os transportes DNS a partir de um nó AKS antes de ativar o LocalDNS:

dig +udp @<custom-dns-ip> <fqdn>
dig +tcp @<custom-dns-ip> <fqdn>

Ambos os comandos devem devolver uma resposta válida. Se o UDP tiver sucesso mas o TCP expirar, não ative o LocalDNS até que a porta TCP 53 seja permitida através do caminho completo da rede e o servidor DNS personalizado esteja configurado para aceitar consultas TCP.

Ativar o LocalDNS num pool de nós

Esta etapa aplica-se tipicamente ao AKS Standard. O AKS Automatic já inclui o LocalDNS pré-configurado.

Para habilitar o LocalDNS durante a criação do pool de nós, use o seguinte comando com seu arquivo de configuração personalizado:

az aks nodepool add --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

Para habilitar o LocalDNS em um pool de nós existente, use o seguinte comando com seu arquivo de configuração personalizado:

az aks nodepool update --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

Desativar o LocalDNS num pool de nós

Desativar o LocalDNS é uma operação avançada e geralmente não é recomendado para os padrões automáticos de produção do AKS, a menos que tenha uma exceção validada.

Para desabilitar o LocalDNS para um pool de nós, você deve atualizar seu arquivo delocaldnsconfig.json definindo a mode propriedade como Disabled. Essa alteração instrui o AKS a desativar o proxy DNS local em todos os nós do pool especificado, revertendo a resolução DNS para o comportamento de cluster padrão. Após atualizar o ficheiro de configuração, aplique-o ao pool de nós usando a CLI do Azure para garantir que a alteração tem efeito.

az aks nodepool update --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --localdns-config ./localdnsconfig.json

Verificar operação LocalDNS

No AKS Automatic, a verificação confirma que a linha base pré-configurada do LocalDNS está ativa para as suas cargas de trabalho. No AKS Standard, a verificação confirma a implementação do seu LocalDNS.

Uma vez ativado o LocalDNS, pode verificar o seu funcionamento executando consultas DNS a partir de pods no pool de nós especificado e inspecionando o SERVER campo nas respostas para confirmar que os endereços LocalDNS são devolvidos (169.254.10.10 ou 169.254.10.11).

Antes de executar as etapas de validação, verifique se as seguintes condições são atendidas:

1. Você tem kubectl instalado e configurado para aceder ao seu cluster AKS.
2. A sua conta de utilizador tem permissões suficientes para criar e aceder aos pods.
3. O pool de nós onde queres validar o LocalDNS está em estado de Pronto .
4. A imagem BusyBox (busybox:1.28) é acessível a partir dos nós do cluster.

Exemplo de validação:

1. Crie um pod de depuração no pool de nós onde o LocalDNS está habilitado:

   kubectl run dnstest --image=busybox:1.28 -- sleep 3600
   

2. Quando o pod estiver em execução, execute o seguinte comando para verificar a resolução DNS:

   kubectl exec -it dnstest -- nslookup kubernetes.default
   

   Verifique a saída. Se localDNS estiver funcionando corretamente, você verá uma resposta com o endereço do servidor 169.254.10.10 ou 169.254.10.11:

   Server:    169.254.10.10
   Address 1: 169.254.10.10
   
   Name:      kubernetes.default
   Address 1: 10.0.0.1 kubernetes.default.svc.cluster.local
   

Configurar LocalDNS

LocalDNS usa um arquivo de configuração baseado em JSON localdnsconfig.json para definir o comportamento de resolução DNS para cada pool de nós. Esse arquivo permite especificar modos operacionais, blocos de servidor para diferentes domínios DNS e configurações de plug-in, como cache, encaminhamento e registro.

Configuração padrão do LocalDNS

No AKS Automatic, o LocalDNS está pré-configurado. Usa a personalização apenas quando tiveres um requisito específico.

No AKS Standard, esta configuração padrão é um bom ponto de partida.

Ao personalizar o LocalDNS, use o seguinte formato de configuração como modelo. Pode definir blocos de servidor extra conforme necessário, mas adicionar propriedades de topo não suportadas ou não padrão à configuração resulta em falhas de validação.

{
  "mode": "Required",
  "vnetDNSOverrides": {
    ".": {
      "queryLogging": "Error",
      "protocol": "PreferUDP",
      "forwardDestination": "VnetDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    },
    "cluster.local": {
      "queryLogging": "Error",
      "protocol": "ForceTCP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    }
  },
  "kubeDNSOverrides": {
    ".": {
      "queryLogging": "Error",
      "protocol": "PreferUDP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    },
    "cluster.local": {
      "queryLogging": "Error",
      "protocol": "ForceTCP",
      "forwardDestination": "ClusterCoreDNS",
      "forwardPolicy": "Sequential",
      "maxConcurrent": 1000,
      "cacheDurationInSeconds": 3600,
      "serveStaleDurationInSeconds": 3600,
      "serveStale": "Immediate"
    }
  }
}

Configurar o mode para LocalDNS

LocalDNS pode ser ativado em três modos possíveis que definem o grau de imposição de LocalDNS para a carga de trabalho.

• Required: O LocalDNS é aplicado ao pool de nós se todos os pré-requisitos forem satisfeitos. Se os requisitos não forem atendidos, a implantação falhará.
• Disabled: Desativa a funcionalidade de DNS local, para que as consultas DNS não sejam resolvidas localmente no nó.
• Preferred: O AKS valida que a sua configuração do LocalDNS está sintaticamente correta, mas não ativa o LocalDNS nos nós. No entanto, aplicar este modo ainda desencadeia uma operação de reimagem de nó, por isso pode testar a sua configuração para erros sem afetar a resolução DNS no cluster.

Para cargas de trabalho de produção no AKS Automatic, mantenha o comportamento pré-configurado do LocalDNS, a menos que tenha uma necessidade validada de personalizar.

A tabela a seguir resume o comportamento do LocalDNS para cada modo e versão do Kubernetes:

Blocos de servidor para LocalDNS

A configuração predefinida aplica-se a consultas de pods usando dnsPolicy:default (em vnetDNSOverrides) e pods usando dnsPolicy:ClusterFirst (em kubeDNSOverrides). Dentro de cada um, há dois blocos de servidor padrão definidos: . e cluster.local.

• . representa todas as consultas DNS externas de pods que tentam resolver domínios públicos ou não clusters (por exemplo, microsoft.com).
• cluster.local representa todas as consultas internas de descoberta de serviços do Kubernetes provenientes de pods que tentam resolver nomes de serviço do Kubernetes ou recursos internos do cluster. Essas consultas são roteadas através do CoreDNS para resolução dentro do cluster.

Plugins suportados para configuração LocalDNS

Regras de validação de configuração

Ao criar sua configuração LocalDNS, esteja ciente destas regras de validação para evitar falhas de implantação:

• Restrições de zona raiz (.): Em vnetDNSOverrides, o forwardDestination para a zona raiz não pode ser ClusterCoreDNS.
• Restrições de zona Cluster.local: Em ambos os casos, vnetDNSOverrides e kubeDNSOverrides, o forwardDestination para cluster.local não pode ser VnetDNS.
• Compatibilidade de protocolo e serveStale: Quando protocol está definido como ForceTCP, serveStale não pode ser definido como Verify. Utilize Immediate em substituição.

Criar um bloco de servidor personalizado no LocalDNS

CoreDNS corresponde consultas a um bloco de servidor específico, baseando-se numa correspondência exata para o domínio que está a ser consultado e não em correspondências parciais. Se você precisar de blocos de servidor personalizados, poderá adicioná-los à sua configuração LocalDNS criando um arquivo chamado localdnsconfig.json com as configurações adicionadas.

Por exemplo, se você tiver necessidades específicas de DNS ao acessar microsoft.com, poderá usar o seguinte bloco de servidor:

"microsoft.com": {
  "queryLogging": "Error",
  "protocol": "ForceTCP",
  "forwardDestination": "ClusterCoreDNS",
  "forwardPolicy": "Sequential",
  "maxConcurrent": 1000,
  "cacheDurationInSeconds": 3600,
  "serveStaleDurationInSeconds": 3600,
  "serveStale": "Immediate"
}

Monitorar LocalDNS

No AKS Automatic, o LocalDNS é pré-configurado, por isso começa com a validação de base e monitoriza o comportamento antes de aplicar ajustes personalizados.

O LocalDNS expõe métricas Prometheus que pode usar para monitorização e alertas. As métricas são expostas na porta 9253 do IP do nó.

Exemplo de configuração de scrape para o add-on Azure Managed Prometheus como DaemonSet:

kind: ConfigMap
apiVersion: v1
metadata:
  name: ama-metrics-prometheus-config-node
  namespace: kube-system
data:
  prometheus-config: |-
    global:
      scrape_interval: 1m
    scrape_configs:
    - job_name: localdns-metrics
      scrape_interval: 1m
      scheme: http
      metrics_path: /metrics
      relabel_configs:
      - source_labels: [__metrics_path__]
        regex: (.*)
        target_label: metrics_path
      - source_labels: [__address__]
        replacement: '$NODE_NAME'
        target_label: instance
      static_configs:
      - targets: ['$NODE_IP:9253']

Solucionar problemas de LocalDNS

As consultas DNS a domínios específicos estão a falhar

Se as consultas DNS para domínios específicos estiverem falhando depois de habilitar o LocalDNS:

1. Verifique se tem sobreposições específicas de domínio no seu localdnsconfig.json que possam estar mal configuradas.

2. Experimente remover temporariamente as substituições específicas de domínio e utilizar apenas a configuração padrão ..

3. Verifique se o problema ocorre com o UDP (User Datagram Protocol) e o TCP (Transmission Control Protocol) ajustando a protocol configuração.

4. Verifique se existem time-outs nos registos do CoreDNS para os endereços LocalDNS 169.254.10.10:53 ou 169.254.10.11:53. A partir de um nó afetado, teste o servidor DNS personalizado upstream separadamente entre UDP e TCP:

   dig +udp @<custom-dns-ip> <fqdn>
   dig +tcp @<custom-dns-ip> <fqdn>
   

   Se o UDP tiver sucesso mas o TCP falhar, verifique se:

   • O servidor DNS personalizado escuta na porta TCP 53.
   • Os NSGs e as firewalls permitem o tráfego pela porta TCP 53 a partir da sub-rede dos nós do AKS.
   • As NVAs e as rotas não descartam nem encaminham de forma assimétrica o tráfego DNS sobre TCP.

   Para desativar o LocalDNS num pool de nós afetado, atualize o seu modo LocalDNS para Disabled. Mudar um pool ativado para Disabled desencadear uma reimagem de nó como parte da atualização. Para uma solução permanente, certifique-se de que o servidor DNS personalizado e o caminho de rede suportam DNS tanto sobre UDP como TCP na porta 53.

Atualizar servidores DNS VNet para LocalDNS

Quando atualizas servidores DNS personalizados diretamente na configuração VNet (usando o portal Azure ou CLI), os nós do cluster AKS não aplicam automaticamente estas alterações. Atualizar as definições DNS ao nível do VNet apenas informa o Fornecedor de Recursos de Rede (NRP), mas não notifica o Fornecedor de Recursos AKS. Como resultado, os nós AKS continuam a usar as definições anteriores do servidor DNS até que tome mais alguma medida.

Para garantir que os nós AKS captem as novas configurações do servidor DNS da rede virtual:

1. Atualize a configuração do DNS da rede virtual usando o portal do Azure ou as APIs, conforme necessário.

2. Use o Provedor de Recursos AKS para reimaginar o pool de nós, garantindo que as definições de DNS atualizadas sejam aplicadas e mantidas.

   az aks nodepool upgrade --resource-group myResourceGroup --cluster-name myAKSCluster --name mynodepool --node-image-only
   

Esse processo garante que o AKS Resource Provider esteja ciente das alterações de DNS e as aplique a todos os nós no pool de nós.

Atualizar as Políticas de Rede da Cilium para permitir a resolução DNS com o LocalDNS

Se implementar Políticas de Rede Cilium no seu cluster, deve permitir explicitamente a saída do pod para os endereços IP do LocalDNS.

As políticas de rede impõem um modelo de negação por defeito para destinos não especificados, pelo que o tráfego DNS para o LocalDNS é bloqueado a menos que seja explicitamente permitido.

• No Azure CNI alimentado por Cilium <=v1.16 com k8s <=1.31, isto pode ser alcançado por uma política baseada em CIDR.
• No Azure CNI Powered by Cilium >=v1.17 com K8s >=1.32, pode ser usada uma Política de Rede Cilium que permite a saída para entidades hospedeiras.

Para uma política de rede Cilium que permita o tráfego em todas as versões, consulte O AKS Local DNS é suportado com o Azure CNI com tecnologia Cilium?

Conteúdo relacionado

• O que é AKS Automatic?
• Criar um cluster automático AKS
• LocalDNS in Azure Kubernetes Service (conceptual)
• Resolução de problemas com o LocalDNS no AKS
• Guia de personalização CoreDNS
• Página do projeto upstream CoreDNS
• Conceitos de rede para aplicações em AKS