Skip to main content

Configurar um Load Balancer de Serviço

Regiões

Este recurso está disponível nas seguintes regiões:
br-se1
br-ne1

As configurações do Load Balancer são realizadas através de Annotations no recurso Service.

warning

Alterar as configurações do Load Balancer manualmente podem torná-lo inutilizável pelo Cluster Kubernetes. Configure-o apenas através de ferramentas como kubectl.

info

As configurações de Load Balancer são diferentes para as versões v3 e v1 do produto de Kubernetes.

Clique aqui para mais informações sobre as versões de plataforma do produto de Kubernetes.

v3​

Abaixo estão listadas as Annotations suportadas pelo Load Balancer na plataforma de produto de Kubernetes versão v3.

Visibilidade (Externo e Interno)​

Define a visibilidade do Load Balancer durante a criação do Service.

Annotation: magalu.cloud/load-balancer-visibility.
Valor padrão: external.
Valores:

  • external: O Load Balancer será exposto à Internet através de um IP público. O IP público será reservado do pool de IPs da Magalu Cloud e será associado ao Load Balancer.
  • internal: O Load Balancer receberá um IP interno da VPC. Essa abordagem permite que você consiga expor a aplicação internamente sem que ela seja acessível através da Internet.

O exemplo abaixo cria um Load Balancer de serviço interno:

cat <<EOF | kubectl apply -f -
kind: Service
apiVersion: v1
metadata:
  name: nginx-internal
  annotations:
    magalu.cloud/load-balancer-visibility: internal
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
EOF

Verifique o IP interno do Load Balancer com o comando abaixo:

kubectl get service nginx-internal -w

NAME             TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
nginx-internal   LoadBalancer   10.104.18.78   <pending>     80:32392/TCP   22s
nginx-internal   LoadBalancer   10.104.18.78   172.18.32.9   80:32392/TCP   30s

Retenção do IP Público​

Define a política de reaproveitamento do IP público durante a exclusão de um Load Balancer de serviço.

Annotation: magalu.cloud/public-ip-reclaim-policy.
Valor padrão: delete.
Valores:

  • retain: Durante a exclusão do Service, o IP público associado ao Load Balancer não será excluído e poderá ser reutilizado. O IP público também será retido caso a Annotation magalu.cloud/load-balancer-public-ip-id seja explicitamente usada.
  • delete: O IP público associado ao Load Balancer será removido durante a exclusão do Service.

No exemplo abaixo, o Service é criado com a Annotation magalu.cloud/public-ip-reclaim-policy, utilizando o valor retain.

cat <<EOF | kubectl apply -f -
kind: Service
apiVersion: v1
metadata:
  name: nginx
  annotations:
    magalu.cloud/public-ip-reclaim-policy: retain
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
EOF

Verifique as informações do Service:

kubectl get service nginx

NAME    TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)        AGE
nginx   LoadBalancer   10.101.170.119   201.23.69.201   80:31198/TCP   34s

É possível consultar as informações do IP público através da CLI da MGC. Verificamos que o seu status atual é in_use.

mgc network public-ips list | grep '201.23.69.201' -C10

[...]
- created_at: 2025-11-21T15:10:52.576443
  description: Public IP for Load Balancer.
  error: null
  external_id: null
  id: 9812d66c-f1ee-4210-aac1-64740d9fce31
  port_id: null
  project_type: default
  public_ip: 201.23.69.201

  # definição do status
  status: in_use

  tenant_id: 00000000-0000-0000-0000-000000000000
  updated: 2025-11-21T15:10:52.576444
  vpc_id: 00000000-0000-0000-0000-000000000000
[...]

Após deletar o Service, podemos verificar que o IP ainda está listado, mas agora seu status é created:

kubectl delete service nginx
mgc network public-ips list | grep '201.23.69.201' -C10

[...]
- created_at: 2025-11-21T15:10:52.576443
  description: Public IP for Load Balancer.
  error: null
  external_id: null
  id: 9812d66c-f1ee-4210-aac1-64740d9fce31
  port_id: null
  project_type: default
  public_ip: 201.23.69.201

  # definição do status
  status: created

  tenant_id: 00000000-0000-0000-0000-000000000000
  updated: 2025-11-21T15:13:20.965765
  vpc_id: 00000000-0000-0000-0000-000000000000
[...]

Utilizando um IP Público Existente​

Para criar um Load Balancer de serviço utilizando um IP público existente é necessário ter um IP público reservado com o status de created.

Caso deseje criar um IP público, confira a documentação aqui.

Annotation: magalu.cloud/load-balancer-public-ip-id.
Valor padrão: "".
Valores:

  • "": Com o valor vazio, o Service cria um IP público durante a criação do Load Balancer.
  • <ip-id>: Ao passar o ID de um IP Público com o status created, o Load Balancer é criado com o IP fornecido.

Aproveitando o exemplo acima, precisamos coletar o ID do IP público:

mgc network public-ips list | grep '201.23.69.201' -C10

[...]
- created_at: 2025-11-21T15:10:52.576443
  description: Public IP for Load Balancer.
  error: null
  external_id: null

  # utilize esse ID
  id: 9812d66c-f1ee-4210-aac1-64740d9fce31

  port_id: null
  project_type: default
  public_ip: 201.23.69.201
  status: created
  tenant_id: 00000000-0000-0000-0000-000000000000
  updated: 2025-11-21T15:13:20.965765
  vpc_id: 00000000-0000-0000-0000-000000000000
[...]

Com o ID em mãos, podemos criar um Load Balancer de serviço com a Annotation magalu.cloud/load-balancer-public-ip-id:

cat <<EOF | kubectl apply -f -
kind: Service
apiVersion: v1
metadata:
  name: nginx-com-ip
  annotations:
    magalu.cloud/load-balancer-public-ip-id: 9812d66c-f1ee-4210-aac1-64740d9fce31
spec:
  selector:
    app: nginx
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
EOF

Verifique as informações do Service:

kubectl get service nginx-com-ip -w

NAME           TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)        AGE
nginx-com-ip   LoadBalancer   10.96.130.94   <pending>      80:32444/TCP   8s
nginx-com-ip   LoadBalancer   10.96.130.94   201.23.69.201  80:32444/TCP   29s

Após a criação do Load Balancer, podemos verificar o status created no IP público:

mgc network public-ips list | grep '201.23.69.201' -C10

[...]
- created_at: 2025-11-21T15:10:52.576443
  description: Public IP for Load Balancer.
  error: null
  external_id: null
  id: 9812d66c-f1ee-4210-aac1-64740d9fce31
  port_id: null
  project_type: default
  public_ip: 201.23.69.201

  # sendo utilizado
  status: in_use

  tenant_id: 00000000-0000-0000-0000-000000000000
  updated: 2025-11-21T15:13:20.965765
  vpc_id: 00000000-0000-0000-0000-000000000000
[...]

PROXY Protocol​

Habilita o PROXY protocol nos backends do Load Balancer. Quando habilitado, o Load Balancer adiciona um cabeçalho com as informações da conexão original (IP e porta do cliente) no início da conexão TCP, permitindo que a aplicação atrás do Load Balancer conheça o endereço real do cliente.

Annotation: magalu.cloud/load-balancer-proxy-protocol.
Valor padrão: desabilitado (Annotation ausente).
Valores:

  • "*": Habilita o PROXY protocol nos backends de todas as portas do Service.
  • Lista de portas do Service separadas por vírgula (ex.: "80,443"): Habilita o PROXY protocol apenas nos backends das portas listadas. Os valores são as portas do Service (spec.ports[].port), não as portas do container ou NodePort.
warning

A aplicação que recebe o tráfego nas portas habilitadas precisa estar configurada para aceitar o PROXY protocol. Caso contrário, as conexões falharão, já que o cabeçalho adicionado pelo Load Balancer não será interpretado corretamente.

Valores inválidos na Annotation (portas fora do range válido ou que não existem no Service) são ignorados e geram eventos de Warning no Service, sem impedir a aplicação das portas válidas. Verifique os eventos com kubectl describe service <nome>.

A Annotation é reconciliada em Load Balancers existentes: é possível habilitar ou desabilitar o PROXY protocol em um Service já criado, sem precisar recriá-lo.

O exemplo abaixo cria um nginx configurado para aceitar o PROXY protocol na porta 8443 do container e um Load Balancer de serviço com o PROXY protocol habilitado apenas na porta 443 do Service:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-proxy-protocol
data:
  default.conf: |
    # Porta sem PROXY protocol.
    server {
        listen 8080;
        location / {
            default_type text/plain;
            return 200 "remote_addr=\$remote_addr\nproxy_protocol_addr=\$proxy_protocol_addr\n";
        }
    }

    # Porta com PROXY protocol: o IP real do cliente é restaurado a partir do cabeçalho.
    server {
        listen 8443 proxy_protocol;
        set_real_ip_from 0.0.0.0/0;
        real_ip_header proxy_protocol;
        location / {
            default_type text/plain;
            return 200 "remote_addr=\$remote_addr\nproxy_protocol_addr=\$proxy_protocol_addr\n";
        }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-proxy-protocol
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-proxy-protocol
  template:
    metadata:
      labels:
        app: nginx-proxy-protocol
    spec:
      containers:
      - name: nginx
        image: nginxinc/nginx-unprivileged:1.27-alpine
        ports:
        - name: plain
          containerPort: 8080
        - name: proxied
          containerPort: 8443
        volumeMounts:
        - name: config
          mountPath: /etc/nginx/conf.d
      volumes:
      - name: config
        configMap:
          name: nginx-proxy-protocol
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-proxy-protocol
  annotations:
    magalu.cloud/load-balancer-proxy-protocol: "443"
spec:
  type: LoadBalancer
  selector:
    app: nginx-proxy-protocol
  ports:
  - name: plain
    port: 80
    protocol: TCP
    targetPort: plain
  - name: proxied
    port: 443
    protocol: TCP
    targetPort: proxied
EOF

Aguarde o IP externo do Load Balancer:

kubectl get service nginx-proxy-protocol -w

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                      AGE
nginx-proxy-protocol   LoadBalancer   10.99.104.201   <pending>       80:30412/TCP,443:31007/TCP   6s
nginx-proxy-protocol   LoadBalancer   10.99.104.201   201.23.72.101   80:30412/TCP,443:31007/TCP   38s

Na porta 80, sem PROXY protocol, a aplicação enxerga apenas o IP interno da conexão:

curl http://201.23.72.101/

remote_addr=192.168.101.34
proxy_protocol_addr=

Na porta 443, com PROXY protocol, a aplicação enxerga o IP real do cliente. Neste exemplo, a porta 443 serve HTTP puro (não TLS), portanto utilize http://:

curl http://201.23.72.101:443/

remote_addr=186.251.145.198
proxy_protocol_addr=186.251.145.198

Para habilitar o PROXY protocol em todas as portas de um Service existente:

kubectl annotate service nginx-proxy-protocol --overwrite \
  magalu.cloud/load-balancer-proxy-protocol='*'

Para desabilitar, remova a Annotation:

kubectl annotate service nginx-proxy-protocol magalu.cloud/load-balancer-proxy-protocol-

Restringindo acesso ao Load Balancer​

Ao utilizar um Load Balancer de serviço, você pode especificar as faixas de IP (CIDRs) que têm permissão para acessá-lo utilizando o campo spec.loadBalancerSourceRanges. Este campo recebe uma lista de CIDRs, utilizado pelo serviço de Load Balancer da Magalu Cloud para configurar sua lista de ACLs.

Por padrão, o acesso ao Load Balancer é liberado para todos os IPs.

info

Atualmente, somente endereços e faixas IPv4 podem ser configurados. Não há suporte para IPv6.

warning

Ao utilizar o campo spec.loadBalancerSourceRanges, você obrigatoriamente precisará incluir a faixa de IPs do Cluster CIDR à lista. Para consultar esse CIDR, utilize o comando abaixo:

mgc kubernetes cluster get <cluster-id>

[...]
cluster_ipv4_cidr: 192.168.0.0/16
[...]

Com o exemplo abaixo, crie Load Balancer de serviço limitando seu acesso para o endereço 186.251.145.190 e para a faixa de IPs 201.23.12.0/24.

Caso o endereço seja um IP único, é necessário adicionar a máscara /32 ao CIDR. Portanto, o endereço 186.251.145.190 se torna 186.251.145.190/32.

cat <<EOF | kubectl apply -f -
kind: Service
apiVersion: v1
metadata:
  name: nginx-com-restricoes
spec:
  loadBalancerSourceRanges:
  - 186.251.145.198/32
  - 201.23.12.0/24
  # Cluster CIDR
  - 192.168.0.0/16
  selector:
    app: nginx
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
EOF

Verifique as informações do Service:

kubectl get service nginx-com-restricoes -w

NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)        AGE
nginx-com-restricoes   LoadBalancer   10.101.235.48   <pending>       80:30584/TCP   4s
nginx-com-restricoes   LoadBalancer   10.101.235.48   201.23.72.176   80:30584/TCP   35s

Caso o seu endereço de IP não esteja na lista, o acesso ao endereço do Load Balancer não será permitido:

curl http://201.23.72.176 --connect-timeout 2

curl: (28) Connection timeout after 2001 ms

v1​

Para os Clusters de plataforma do produto de Kubernetes na versão v1, todas as Annotations disponíveis estão documentadas aqui.