Skip to content

Istio & Gateway API

Objetivo

Esta página documenta como o módulo de Istio expõe as aplicações dos ambientes HML e NOX usando Gateway API, TLS wildcard e integração com o ExternalDNS.

Fonte de verdade no pipeline

Os arquivos principais são:

  • infrastructure/modules/istio/templates/gateway.tpl
  • infrastructure/modules/istio/templates/redirect-http-to-https.tpl
  • infrastructure/modules/istio/main.tf
  • infrastructure/modules/istio/locals.tf
  • config/hml/istio/config.hcl
  • config/nox/istio/config.hcl

Configuração de ambiente

Exemplo real em HML:

terraform namespace = "istio-system" chart_version = "1.27.3" kiali_chart_version = "2.18.0" lb_min_bandwidth = "10" lb_max_bandwidth = "100" domain = "nox.app.br" ingress_domain = "nox.app.br" lb_publlic_ip = "163.176.171.85"

Os mesmos campos existem em NOX, com outro valor de lb_publlic_ip.

O Gateway criado pelo módulo

O template gateway.tpl gera um Gateway com listeners HTTP e HTTPS:

yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: gateway namespace: istio-system annotations: oci.oraclecloud.com/load-balancer-type: lb service.beta.kubernetes.io/oci-load-balancer-internal: "true" service.beta.kubernetes.io/oci-load-balancer-shape: flexible service.beta.kubernetes.io/oci-load-balancer-shape-flex-min: "${LB_MIN_BANDWIDTH}" service.beta.kubernetes.io/oci-load-balancer-shape-flex-max: "${LB_MAX_BANDWIDTH}" cert-manager.io/cluster-issuer: "${CLUSTER_ISSUER}" spec: gatewayClassName: istio listeners: - name: http port: 80 protocol: HTTP hostname: "*.${DOMAIN}" - name: https port: 443 protocol: HTTPS hostname: "*.${DOMAIN}" tls: certificateRefs: - name: ${DOMAIN}-tls

Como isso funciona

Wildcard hostname

O Gateway aceita hosts no padrão *.nox.app.br. Isso permite que múltiplos tenants e aplicações publiquem HTTPRoute sem precisar de um Gateway por hostname.

Wildcard TLS

O listener HTTPS referencia o secret ${DOMAIN}-tls. Com a configuração atual, isso significa um secret como nox.app.br-tls no namespace do Gateway.

Listener compartilhado

Os HTTPRoute podem ser criados em qualquer namespace porque o Gateway usa:

yaml allowedRoutes: namespaces: from: All

Redirecionamento HTTP para HTTPS

O módulo também aplica um HTTPRoute dedicado para redirecionar tráfego do listener HTTP para HTTPS com status 301.

Isso reduz necessidade de repetir essa política em cada aplicação.

Como o DNS descobre o target

Depois que o Gateway é criado, o módulo adiciona a annotation:

terraform resource "kubernetes_annotations" "gateway_annotations" { annotations = { "external-dns.alpha.kubernetes.io/target" = local.lb_publlic_ip } }

Esse é o ponto de ligação entre o Gateway e o ExternalDNS. O controller observa o recurso e publica o hostname apontando para esse target.

lb_publlic_ip: o que realmente significa

O valor final é calculado em locals.tf assim:

terraform service_lb_address = data.kubernetes_service_v1.gateway_istio.status[0].load_balancer[0].ingress[0].ip lb_publlic_ip = var.lb_publlic_ip != "" ? var.lb_publlic_ip : local.service_lb_address

Regra prática

  • se lb_publlic_ip estiver vazio, o módulo publica no DNS o IP descoberto do service do Gateway
  • se lb_publlic_ip estiver preenchido, ele sobrescreve o target publicado no DNS

No cenário atual

O Gateway cria um load balancer interno porque a annotation oci-load-balancer-internal: "true" está fixa no template.

Portanto, quando há firewall ou NAT na borda, o campo lb_publlic_ip deve ser preenchido com:

  • o IP público do firewall/NAT que recebe tráfego de internet
  • e não com o IP privado do balanceador interno OCI

Essa é a interpretação correta do parâmetro para HML e NOX.

Arquitetura esperada com NAT/firewall

flowchart LR
    CLIENT[Cliente] --> DNS[OCI DNS]
    DNS --> EDGE[IP publico em lb_publlic_ip]
    EDGE --> FW[Firewall / NAT]
    FW --> ILB[Load Balancer interno do Gateway]
    ILB --> ISTIO[Gateway do Istio]
    ISTIO --> ROUTE[HTTPRoute]
    ROUTE --> APP[Aplicação]

O que o módulo faz vs. o que fica fora dele

O que o módulo faz

  • instala Istio
  • cria o Gateway
  • configura listeners HTTP/HTTPS
  • referencia o certificado wildcard
  • injeta external-dns.alpha.kubernetes.io/target

O que depende da borda externa

  • existência do firewall/NAT público
  • regra de encaminhamento 80/443 para o balanceador interno
  • política de segurança de rede fora do cluster

Se a infraestrutura de borda não existir ou não encaminhar corretamente, o DNS será criado, mas o tráfego não chegará à aplicação.

Onde ajustar

HML

  • config/hml/istio/config.hcl

NOX

  • config/nox/istio/config.hcl

Os principais campos operacionais são:

  • domain
  • ingress_domain
  • lb_min_bandwidth
  • lb_max_bandwidth
  • lb_publlic_ip

Relação com os charts das aplicações

Os charts precisam criar HTTPRoute compatível com:

  • hostname dentro do domínio filtrado
  • Gateway correto
  • annotation de ExternalDNS

Para o padrão esperado de charts, veja Helm Charts — Padrões.