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

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

Para a maioria das cargas de trabalho de produção, o AKS Automatic é a opção padrão recomendada e pronta para uso em produção no AKS. LocalDNS é 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.

LocalDNS é um recurso no AKS que melhora o desempenho de resolução de DNS e a resiliência para cargas de trabalho em execução em seu cluster. Ao executar um proxy DNS em cada nó, o LocalDNS reduz a latência de consulta DNS, melhora a confiabilidade durante interrupções transitórias de rede e fornece controles avançados de cache e encaminhamento quando você precisa de personalização.

Para saber o que é o LocalDNS, incluindo detalhes da arquitetura e principais recursos, consulte a Resolução de DNS no AKS (Serviço de Kubernetes do Azure).

Comportamento de LocalDNS automático do AKS e do AKS Standard

Verificações de compatibilidade para o modo Preferred

A partir do Kubernetes 1.37, o AKS Standard atribui o modo Preferred 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 habilitar inicialmente o LocalDNS no Preferred modo, o AKS verifica os seguintes requisitos de compatibilidade. Se um requisito não for atendido, LocalDNS permanecerá desabilitado.

Depois que o AKS habilita o LocalDNS no modo Preferred, ele continua habilitado durante atualizações subsequentes não relacionadas do pool de nós. Para desabilitá-lo, defina explicitamente o LocalDNS mode como Disabled.

Práticas recomendadas para a configuração do LocalDNS

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

• Comece com uma configuração mínima: comece com uma configuração simples que usa o Preferred modo para validar a sintaxe de configuração do LocalDNS antes de mover para o Required modo. O Preferred modo valida sua configuração sem habilitar o LocalDNS, permitindo que você capture erros de configuração antecipadamente sem afetar o cluster.
• Implementar estratégias de cache adequadas: defina as configurações de cache com base nas características da 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 de 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 as 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 o melhor esforço e não garante respostas desatualizadas. O cache é dividido em 256 fragmentos e com um máximo padrão de 10.000 entradas, permitindo que cada fragmento mantenha 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 expiradas. Como resultado, um registro obsoleto pode nem sempre estar disponível, especialmente em alto volume de consulta.
• Monitorar o desempenho do DNS: depois de habilitar o LocalDNS, monitore o desempenho DNS do aplicativo usando:
  • Métricas de desempenho do aplicativo.
  • Métricas de nó para detectar a redução da pressão de rede.
  • Entradas de log quando queryLogging é definida como Log.
• Siga o princípio de privilégio mínimo: ao configurar regras de encaminhamento de DNS, permita apenas o acesso aos servidores e domínios DNS necessários.
• Teste antes da implantação de produção: sempre teste a configuração localDNS em um ambiente de não produção antes de distribuí-la para clusters de produção.
• Usar a IaC (Infraestrutura como Código): armazene seu arquivo localdnsconfig.json em seu repositório de infraestrutura e inclua-o em seus modelos de implantação do AKS.
• Configuração de rede para encaminhamento TCP: ao usar o TCP para encaminhamento de DNS para VnetDNS, verifique se seus NSGs (Grupos de Segurança de Rede), firewalls ou NVAs (Dispositivos Virtuais de Rede) não bloqueiam o tráfego TCP entre servidores CoreDNS/LocalDNS e VnetDNS.
• Evite habilitar o DNSCache NodeLocal e o LocalDNS: não é recomendável habilitar o DNSCache nodeLocal do Kubernetes upstream e o LocalDNS no pool de nós. Embora o AKS não bloqueie essa configuração, todo o tráfego DNS é roteado por meio do LocalDNS, o que pode levar a um comportamento inesperado ou a benefícios reduzidos do DNSCache NodeLocal.
• Não imponha um limite de conexão TCP no servidor DNS personalizado upstream antes de habilitar o LocalDNS: quando você habilita o LocalDNS em um pool de nós, cada nó abre conexões TCP de longa duração de seu proxy DNS local para o resolvedor upstream, em vez das pequenas trocas UDP usadas anteriormente. Se o servidor DNS personalizado (como BIND, Unbound, Windows DNS ou um dispositivo de terceiros) estiver configurado com um limite fixo de conexões de cliente TCP simultâneas ou se você tiver ajustado esse limite com base no tráfego pré-LocalDNS, as novas conexões TCP do LocalDNS poderão ser rejeitadas, causando falhas de resolução de DNS em todo o cluster. Deixe qualquer limite de conexão TCP no valor padrão, com uma margem folgada, antes de ativar o LocalDNS; valide o número de conexões TCP em regime estável em nós do AKS após a ativação; e só ajuste o limite, mantendo folga para a expansão de nós, atualizações e reimagem de nós.

Pré-requisitos

Os clusters automáticos do AKS incluem LocalDNS pré-configurado. Os pré-requisitos nesta seção se aplicam principalmente quando você habilita ou personaliza o comportamento localDNS, que é mais comum em cenários de personalização padrão e avançados do AKS.

• Você deve ter um cluster AKS existente com as versões do Kubernetes 1.31 e posteriores para usar o LocalDNS. Se precisar de um cluster do AKS, você poderá criar um usando CLI do Azure, Azure PowerShell ou o portal Azure.
• Este artigo requer CLI do Azure versão 2.80.0 e posterior. Se você estiver usando Azure Cloud Shell, a versão mais recente já está instalada.
• O LocalDNS só tem suporte em pools de nós que executam Azure Linux ou Ubuntu 22.04 e mais recentes.
• A SKU da VM (Máquina Virtual) usada para o pool de nós deve ter pelo menos 4 vCPUs (núcleos) para dar suporte ao LocalDNS.

Habilitar ou personalizar o LocalDNS em um cluster do AKS

Configure o LocalDNS no nível do pool de nós no AKS, para que você possa adaptar o comportamento por carga de trabalho e ambiente.

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

No AKS Standard, use esta seção para habilitar e configurar o LocalDNS.

Validar o DNS personalizado antes de habilitar o LocalDNS

Se sua rede virtual usar servidores DNS personalizados, teste os dois transportes DNS em um nó do AKS antes de habilitar o LocalDNS:

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

Ambos os comandos devem retornar uma resposta válida. Se o UDP for bem-sucedido, mas o TCP atingir o tempo limite, não habilite o LocalDNS até que a porta TCP 53 seja permitida por meio do caminho de rede completo e o servidor DNS personalizado esteja configurado para aceitar consultas TCP.

Habilitar o LocalDNS em um pool de nós

Essa etapa normalmente se aplica ao AKS Standard. O AKS Automatic já inclui LocalDNS pré-configurado.

Para habilitar o LocalDNS durante a criação do pool de nós, use o seguinte comando com o 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 o arquivo de configuração personalizado:

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

Desativar o LocalDNS em um pool de nós

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

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

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

Verificar a operação LocalDNS

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

Depois que o LocalDNS estiver habilitado, você poderá verificar sua operação executando consultas DNS de pods no pool de nós especificado e inspecionando o SERVER campo nas respostas para confirmar se os endereços LocalDNS são retornados (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ê instalou kubectl e configurou para acessar o cluster do AKS.
2. Sua conta de usuário tem permissões suficientes para criar e executar comandos dentro de pods.
3. O pool de nós em que você deseja validar o LocalDNS está em um estado Pronto .
4. A imagem BusyBox (busybox:1.28) está acessível a partir dos nós de cluster.

Exemplo de validação:

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

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

2. Depois que 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 o localDNS estiver funcionando corretamente, você deverá 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 o LocalDNS

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

Configuração localDNS padrão

No AKS Automatic, LocalDNS é pré-configurado. Use a personalização somente quando você tiver um requisito específico.

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

Ao personalizar o LocalDNS, use o seguinte formato de configuração como modelo. Você pode definir blocos de servidor extras conforme necessário, mas adicionar propriedades de nível superior sem suporte 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

O LocalDNS pode ser habilitado em três modos possíveis que definem a extensão da imposição do LocalDNS para a carga de trabalho:

• Required: o LocalDNS é imposto no pool de nós se todos os pré-requisitos forem atendidos. Se os requisitos não forem atendidos, a implantação falhará.
• Disabled: desabilita o recurso DNS local, portanto, as consultas DNS não são resolvidas localmente no nó.
• Preferred: o AKS valida que a configuração do LocalDNS está sintaticamente correta, mas não habilita o LocalDNS nos nós. No entanto, aplicar esse modo ainda aciona uma operação de recriação da imagem do nó, para que você possa verificar se há erros na sua configuração sem afetar a resolução de DNS no cluster.

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

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

Blocos de servidor para LocalDNS

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

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

Plug-ins com suporte para configuração de LocalDNS

Regras de validação de configuração

Ao criar sua configuração de LocalDNS, lembre-se dessas regras de validação para evitar falhas de implantação:

• Restrições da zona raiz (.): sob vnetDNSOverrides, a forwardDestination para a zona raiz não pode ser ClusterCoreDNS.
• Restrições de zona cluster.local: em ambos vnetDNSOverrides e kubeDNSOverrides, o forwardDestination para cluster.local não pode ser VnetDNS.
• Compatibilidade de protocolo e serveStale: quando protocol é definido como ForceTCP, serveStale não pode ser definido como Verify. Use Immediate em seu lugar.

Criar um bloco de servidor personalizado no LocalDNS

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

Por exemplo, se você tiver necessidades de DNS específicas 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, portanto, comece com a validação de linha de base e monitore o comportamento antes de aplicar o ajuste personalizado.

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

Exemplo de configuração de coleta para Azure Managed Prometheus add-on as a 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 para domínios específicos estão falhando

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

1. Verifique se você tem substituições específicas do domínio em seu localdnsconfig.json que podem estar configuradas incorretamente.

2. Experimente remover temporariamente modificações específicas do domínio e usar apenas a configuração padrão ..

3. Verifique se o problema ocorre com o UDP (User Datagram Protocol) e o Protocolo de Controle de Transmissão (TCP) ajustando a protocol configuração.

4. Verifique os logs do CoreDNS para obter tempo limite para os endereços 169.254.10.10:53 LocalDNS ou 169.254.10.11:53. Em um nó afetado, teste o servidor DNS personalizado upstream separadamente em UDP e TCP:

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

   Se o UDP funcionar, mas o TCP não, verifique se:

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

   Para desabilitar o LocalDNS em um pool de nós afetado, atualize seu modo LocalDNS para Disabled. Alterar um pool habilitado para Disabled leva a refazer a imagem do nó como parte da atualização. Para uma solução permanente, verifique se o servidor DNS personalizado e o caminho de rede suportam DNS por UDP e TCP na porta 53.

Atualizar servidores DNS da VNet para LocalDNS

Quando você atualiza servidores DNS personalizados diretamente na configuração da VNet (usando o portal Azure ou a CLI), os nós de cluster do AKS não aplicam essas alterações automaticamente. Atualizar as configurações de DNS no nível da VNet informa apenas o NRP (Provedor de Recursos de Rede), mas não notifica o Provedor de Recursos do AKS. Como resultado, os nós do AKS continuam a usar as configurações anteriores do servidor DNS até que você tome mais medidas.

Para garantir que os nós do AKS peguem as novas configurações do servidor DNS da VNet:

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

2. Use o Provedor de Recursos do AKS para refazer a imagem do pool de nós, garantindo que as configurações de DNS atualizadas sejam aplicadas e retidas:

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

Esse processo garante que o Provedor de Recursos do AKS esteja ciente das alterações de DNS e as aplica a todos os nós no pool de nós.

Atualizar políticas de rede do Cilium para permitir a resolução de DNS com o LocalDNS

Se você implantar as políticas de rede Cilium em seu cluster, deverá 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 padrão para destinos que não são especificados, portanto, o tráfego DNS para LocalDNS é bloqueado, a menos que seja explicitamente permitido.

• No Azure CNI Powered by Cilium <=v1.16 com k8s <=1.31, isso pode ser implementado por meio de uma política baseada em CIDR.
• Já no Azure CNI Powered by Cilium >=v1.17 com K8s >=1.32, é possível utilizar uma Política de Rede do Cilium que permita tráfego de saída para entidades de host.

Para obter uma política de rede Cilium que permite o tráfego em todas as versões, consulte O DNS local do AKS tem suporte com Azure CNI alimentado pelo Cilium?

Conteúdo relacionado

• O que é o AKS Automatic?
• Criar um cluster automático do AKS
• LocalDNS em Serviço de Kubernetes do Azure (conceitual)
• Solucionar problemas de LocalDNS no AKS
• Guia de personalização do CoreDNS
• Página do projeto upstream do CoreDNS
• Conceitos de rede para aplicativos no AKS