Configuração de Proxy em Clusters Kubernetes: Guia Completo para Engenheiros DevOps

Ao implantar o Kubernetes em um ambiente corporativo ou atrás de um firewall, frequentemente surge a necessidade de configurar um servidor proxy para acessar recursos externos. Isso é crucial para baixar imagens de contêineres, atualizar pacotes e interagir com APIs externas. Neste guia, abordaremos todos os níveis de configuração de proxy no Kubernetes — desde a configuração de nós até pods individuais.

Por que precisamos de proxy em clusters Kubernetes

Clusters Kubernetes em ambientes corporativos frequentemente operam em redes isoladas com acesso limitado à internet. Um servidor proxy resolve várias questões críticas:

• Baixar imagens de contêineres — Docker Hub, Google Container Registry, repositórios privados exigem acesso externo
• Atualização de pacotes — instalação de dependências via apt, yum, pip dentro de contêineres
• Acesso a APIs externas — integração com serviços em nuvem, monitoramento, logging
• Segurança — controle de tráfego, filtragem de domínios, registro de solicitações
• Cache — aceleração de solicitações repetidas aos mesmos recursos

Sem a configuração correta do proxy, você enfrentará erros como "image pull failed", "connection timeout" ou "network unreachable" ao tentar implantar aplicativos. Isso é especialmente crítico para pipelines automáticos de CI/CD, onde cada segundo de inatividade custa dinheiro.

Níveis de configuração de proxy no Kubernetes

O Kubernetes possui uma arquitetura em múltiplos níveis, e o proxy deve ser configurado em cada nível, dependendo das tarefas:

Cada nível requer uma configuração separada, e pular qualquer um deles pode levar a problemas. Por exemplo, se você configurar o proxy apenas para o Docker, mas não para os pods, as imagens serão baixadas, mas os aplicativos dentro dos contêineres não conseguirão acessar APIs externas.

Configuração de proxy para Docker e containerd

O runtime de contêiner é o primeiro componente que precisa ser configurado, pois é ele quem é responsável por baixar imagens de contêineres de repositórios externos. Vamos ver a configuração para ambos os runtimes populares.

Configuração de proxy para Docker

Para o Docker, você precisa criar um arquivo drop-in do systemd que adicionará variáveis de ambiente ao serviço Docker:

# Crie o diretório para a configuração
sudo mkdir -p /etc/systemd/system/docker.service.d

# Crie o arquivo com as configurações do proxy
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.cluster.local,.svc"
EOF

# Recarregue a configuração do systemd
sudo systemctl daemon-reload

# Reinicie o Docker
sudo systemctl restart docker

# Verifique se as configurações foram aplicadas
sudo systemctl show --property=Environment docker

Depois disso, o Docker poderá baixar imagens através do servidor proxy. Você pode verificar o funcionamento com o comando:

docker pull nginx:latest

Configuração de proxy para containerd

O containerd é usado em clusters Kubernetes modernos como o principal runtime de contêiner. A configuração do proxy para ele é um pouco diferente:

# Crie o diretório para a configuração
sudo mkdir -p /etc/systemd/system/containerd.service.d

# Crie o arquivo com as configurações do proxy
sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.cluster.local,.svc"
EOF

# Recarregue a configuração
sudo systemctl daemon-reload
sudo systemctl restart containerd

# Verifique o status
sudo systemctl status containerd

Configuração de proxy para kubelet

O kubelet é o agente do Kubernetes que opera em cada nó do cluster. Ele também precisa de acesso ao servidor API e a recursos externos. A configuração depende da forma como o Kubernetes foi instalado.

Para clusters kubeadm

Se você estiver usando kubeadm, configure o proxy através do systemd:

# Crie o diretório para a configuração do kubelet
sudo mkdir -p /etc/systemd/system/kubelet.service.d

# Crie o arquivo com as configurações do proxy
sudo tee /etc/systemd/system/kubelet.service.d/http-proxy.conf <<EOF
[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,10.96.0.0/12,10.244.0.0/16,.cluster.local,.svc"
EOF

# Recarregue o kubelet
sudo systemctl daemon-reload
sudo systemctl restart kubelet

Para Kubernetes gerenciado (EKS, GKE, AKS)

Em serviços Kubernetes gerenciados, a configuração do kubelet geralmente é feita através de parâmetros de inicialização dos nós ou scripts de dados do usuário. Por exemplo, para AWS EKS:

#!/bin/bash
# Script de dados do usuário para nós de trabalho EKS

# Configuração do proxy para o sistema
cat <<EOF >> /etc/environment
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1,169.254.169.254,.ec2.internal,.cluster.local
EOF

# Configuração para kubelet
mkdir -p /etc/systemd/system/kubelet.service.d
cat <<EOF > /etc/systemd/system/kubelet.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://proxy.company.com:8080"
Environment="HTTPS_PROXY=http://proxy.company.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,169.254.169.254,.ec2.internal,.cluster.local"
EOF

systemctl daemon-reload
systemctl restart kubelet

Note a adição de 169.254.169.254 ao NO_PROXY — este é o endereço do serviço de metadados da AWS, que deve estar acessível sem proxy.

Configuração de proxy no nível de pods

Mesmo que você tenha configurado o proxy para Docker e kubelet, os aplicativos dentro dos pods não usarão automaticamente o proxy. É necessário especificar explicitamente as variáveis de ambiente nos manifests do Kubernetes.

Configuração através do manifest de Deployment

A maneira mais simples é adicionar variáveis de ambiente na especificação do contêiner:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-company/my-app:latest
        env:
        - name: HTTP_PROXY
          value: "http://proxy.company.com:8080"
        - name: HTTPS_PROXY
          value: "http://proxy.company.com:8080"
        - name: NO_PROXY
          value: "localhost,127.0.0.1,.cluster.local,.svc,10.0.0.0/8"
        ports:
        - containerPort: 8080

Uso de ConfigMap para configuração centralizada

Para evitar duplicar as configurações de proxy em cada Deployment, crie um ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: proxy-config
  namespace: default
data:
  HTTP_PROXY: "http://proxy.company.com:8080"
  HTTPS_PROXY: "http://proxy.company.com:8080"
  NO_PROXY: "localhost,127.0.0.1,.cluster.local,.svc,10.0.0.0/8"

Em seguida, use este ConfigMap no Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: app
        image: my-company/my-app:latest
        envFrom:
        - configMapRef:
            name: proxy-config

Essa abordagem simplifica o gerenciamento: ao alterar o endereço do proxy, basta atualizar o ConfigMap, e após a reinicialização dos pods, as novas configurações serão aplicadas automaticamente.

Injeção automática através do MutatingWebhook

Para adicionar automaticamente as variáveis de proxy em todos os pods, você pode usar o MutatingAdmissionWebhook. Esta é uma abordagem avançada que requer o desenvolvimento de um serviço webhook próprio, mas permite gerenciar centralizadamente as configurações sem modificar os manifests dos aplicativos.

Configuração correta do NO_PROXY

A variável NO_PROXY define quais endereços e domínios devem contornar o servidor proxy. Uma configuração incorreta do NO_PROXY é a causa mais comum de problemas em clusters Kubernetes.

Exceções obrigatórias para Kubernetes

Os seguintes endereços e intervalos DEVEM sempre estar no NO_PROXY:

Exemplo de configuração completa do NO_PROXY

NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,10.96.0.0/12,.cluster.local,.svc,.default.svc,.default.svc.cluster.local,kubernetes.default.svc,kubernetes.default.svc.cluster.local

Configuração do kubectl para trabalhar através do proxy

Se você gerencia um cluster a partir de uma estação de trabalho que está atrás de um proxy, configure as variáveis de ambiente para o kubectl:

# Para Linux/macOS - adicione ao ~/.bashrc ou ~/.zshrc
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,kubernetes.default.svc,.cluster.local

# Para Windows PowerShell
$env:HTTP_PROXY="http://proxy.company.com:8080"
$env:HTTPS_PROXY="http://proxy.company.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,kubernetes.default.svc,.cluster.local"

Depois disso, o kubectl poderá se conectar ao servidor API do cluster através do proxy. Verifique o funcionamento:

kubectl cluster-info
kubectl get nodes

Configuração de proxy com autenticação

Se o servidor proxy exigir autenticação, adicione as credenciais na URL:

export HTTP_PROXY=http://username:password@proxy.company.com:8080
export HTTPS_PROXY=http://username:password@proxy.company.com:8080

Diagnóstico e resolução de problemas comuns

Mesmo com a configuração correta, podem surgir problemas. Vamos abordar os erros mais comuns e como resolvê-los.

Erro "ImagePullBackOff" ao baixar imagens

Sintomas: Os pods não iniciam, nos eventos aparece o erro "Failed to pull image" ou "connection timeout".

Diagnóstico:

# Verifique os eventos do pod
kubectl describe pod <pod-name>

# Verifique as configurações de proxy no Docker/containerd
sudo systemctl show --property=Environment docker
sudo systemctl show --property=Environment containerd

# Tente baixar a imagem manualmente no nó
sudo docker pull nginx:latest
sudo crictl pull nginx:latest

Solução: Certifique-se de que o proxy está configurado para o runtime de contêiner e que o domínio do repositório de imagens não está no NO_PROXY.

Problemas com resolução de DNS dentro do cluster

Sintomas: Os pods não conseguem se comunicar entre si por nomes DNS (por exemplo, service-name.namespace.svc.cluster.local).

Diagnóstico:

# Verifique o DNS a partir do pod
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default

# Verifique as variáveis de proxy no pod
kubectl exec -it <pod-name> -- env | grep PROXY

Solução: Adicione .cluster.local e .svc ao NO_PROXY.

Desempenho lento ou timeouts ao acessar APIs externas

Sintomas: Os aplicativos funcionam lentamente ou recebem timeout ao fazer solicitações a serviços externos.

Diagnóstico:

# Verifique a disponibilidade do proxy a partir do pod
kubectl exec -it <pod-name> -- curl -v -x http://proxy.company.com:8080 https://www.google.com

# Meça o tempo de resposta
kubectl exec -it <pod-name> -- time curl -x http://proxy.company.com:8080 https://api.example.com

Solução: O problema pode estar na performance do servidor proxy. Considere usar proxies residenciais com localização geográfica próxima para reduzir latências.

Erros SSL/TLS ao trabalhar através do proxy

Sintomas: Erros como "certificate verify failed" ou "SSL handshake failed".

Causa: Alguns servidores proxy realizam inspeção SSL (descriptografando o tráfego HTTPS), o que requer a instalação do certificado raiz do proxy.

Solução:

# Crie um ConfigMap com o certificado do proxy
kubectl create configmap proxy-ca-cert --from-file=ca.crt=/path/to/proxy-ca.crt

# Monte o certificado no pod e adicione ao armazenamento de sistema
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: app
        volumeMounts:
        - name: proxy-ca
          mountPath: /usr/local/share/ca-certificates/proxy-ca.crt
          subPath: ca.crt
      volumes:
      - name: proxy-ca
        configMap:
          name: proxy-ca-cert

Melhores práticas para proxy em produção

Com base na experiência de operação de clusters Kubernetes em ambientes corporativos, aqui estão recomendações para um funcionamento confiável com proxy:

1. Use servidores proxy de alta disponibilidade

O proxy se torna um único ponto de falha para todo o cluster. Configure vários servidores proxy atrás de um balanceador de carga:

HTTP_PROXY=http://proxy-lb.company.com:8080

Onde proxy-lb.company.com é o balanceador de carga na frente de vários servidores proxy.

2. Gerenciamento centralizado de configuração

Use ConfigMap ou Secret para armazenar as configurações do proxy em vez de codificá-las em cada manifest:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-proxy-config
  namespace: kube-system
data:
  HTTP_PROXY: "http://proxy-lb.company.com:8080"
  HTTPS_PROXY: "http://proxy-lb.company.com:8080"
  NO_PROXY: "localhost,127.0.0.1,.cluster.local,.svc,10.0.0.0/8"

3. Monitoramento e alertas

Configure o monitoramento da disponibilidade dos servidores proxy e alertas em caso de problemas:

• Tempo de resposta do proxy (deve ser < 100ms para proxies locais)
• Número de erros de conexão ao proxy
• Número de eventos ImagePullBackOff no cluster
• Uso de CPU e rede nos servidores proxy

4. Documente as exceções do NO_PROXY

Mantenha documentação sobre quais domínios e endereços IP foram adicionados ao NO_PROXY e por quê. Isso ajudará na resolução de problemas e auditoria de segurança.

5. Teste as alterações no ambiente de desenvolvimento

Antes de alterar as configurações do proxy em produção, sempre teste em um cluster de desenvolvimento/staging:

# Pod de teste para verificar o proxy
apiVersion: v1
kind: Pod
metadata:
  name: proxy-test
spec:
  containers:
  - name: test
    image: curlimages/curl:latest
    command: ["sleep", "3600"]
    env:
    - name: HTTP_PROXY
      value: "http://new-proxy.company.com:8080"
    - name: HTTPS_PROXY
      value: "http://new-proxy.company.com:8080"

# Verifique a disponibilidade de recursos externos
kubectl exec -it proxy-test -- curl -v https://registry.k8s.io
kubectl exec -it proxy-test -- curl -v https://docker.io

6. Use diferentes tipos de proxy para diferentes tarefas

Para componentes críticos (download de imagens, API do cluster), use proxies rápidos de data center, e para aplicativos que exigem diversidade geográfica de IP — proxies residenciais ou móveis.

7. Atualize regularmente a lista do NO_PROXY

Ao adicionar novos serviços ou alterar a topologia da rede, atualize o NO_PROXY. Automatize isso através de Helm charts ou Kustomize:

# values.yaml para Helm chart
proxy:
  enabled: true
  http: "http://proxy.company.com:8080"
  https: "http://proxy.company.com:8080"
  noProxy:
    - localhost
    - 127.0.0.1
    - .cluster.local
    - .svc
    - 10.0.0.0/8
    - internal-service.company.com

Conclusão

A configuração de proxy em clusters Kubernetes é uma tarefa em múltiplos níveis que requer atenção aos detalhes em cada nível: desde o sistema operacional e runtime de contêiner até pods individuais. A configuração correta garante a operação contínua do cluster, acesso seguro a recursos externos e conformidade com as políticas de segurança corporativas.

Pontos-chave a serem lembrados:

• Configure o proxy em todos os níveis: OS, runtime de contêiner, kubelet, pods
• Configure corretamente o NO_PROXY, incluindo todas as redes internas do cluster
• Use gerenciamento centralizado através de ConfigMap
• Monitore a disponibilidade e o desempenho dos servidores proxy
• Teste as alterações antes de aplicá-las em produção

Para clusters Kubernetes críticos, recomendamos o uso de proxies de data center confiáveis com alta disponibilidade e baixa latência. Isso garantirá a operação estável da infraestrutura e minimizará os riscos de inatividade devido a problemas de acesso à rede.

Ao enfrentar problemas, use uma abordagem sistemática para diagnóstico: verifique as configurações em cada nível, analise logs e eventos, teste a conexão manualmente. A maioria dos problemas com proxy no Kubernetes é resolvida com a configuração correta das variáveis de ambiente e do NO_PROXY.