Configure CORS policies for Nginx Ingress - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Como funciona

O CORS gerencia dois tipos de requisição: simples e preflight.

Uma requisição simples é enviada diretamente ao servidor:

O navegador adiciona o cabeçalho Origin à requisição (por exemplo, Origin: https://example.com).
O controlador do Nginx Ingress compara o método HTTP e o valor de Origin com a configuração de CORS. Se houver correspondência, ele adiciona Access-Control-Allow-Origin à resposta.
O navegador verifica se Access-Control-Allow-Origin corresponde à origem da requisição. A correspondência indica sucesso; um cabeçalho ausente ou divergente indica falha.

Uma requisição preflight envia uma verificação OPTIONS antes da requisição principal:

O navegador envia uma requisição OPTIONS com Access-Control-Request-Method e Access-Control-Request-Headers para descrever a requisição real.
Se o método ou os cabeçalhos não forem permitidos, o preflight falha e a requisição principal nunca é enviada. Caso o preflight tenha sucesso, a requisição principal prossegue como uma requisição simples.

Uma requisição aciona um preflight quando:

O método não é GET, HEAD ou POST.
O método é POST e Content-Type não é text/plain, application/x-www-form-urlencoded ou multipart/form-data.
A requisição inclui um cabeçalho personalizado.

Importante

Quando cors-allow-credentials for "true", não defina cors-allow-origin como "*". A especificação W3C proíbe essa combinação: quando uma requisição carrega credenciais (como cookies), o servidor deve nomear explicitamente a origem confiável. O uso de "*" permite que qualquer site envie requisições autenticadas em nome do usuário, o que representa um risco de segurança.

Configure CORS

Pré-requisitos

Antes de começar, certifique-se de ter:

Um cluster ACK com o controlador Nginx Ingress implantado
Um recurso de Ingress que roteie tráfego para seu serviço de backend
Permissões para editar recursos de Ingress no cluster

Adicionar anotações de CORS

Faça login no console do ACK. No painel de navegação à esquerda, escolha Clusters.
Na página Clusters, clique em Network > Ingresses.
Na página Ingresses, localize o Ingress desejado e clique em Edit YAML na coluna Actions.
Adicione as anotações de CORS em metadata.annotations conforme o seu cenário.

Cenário A: Requisições com credenciais ou cookies (recomendado)

Use esta configuração quando seu frontend (https://example.com ou https://app.example.com) enviar credenciais (como cookies ou um cabeçalho Authorization) para uma API de backend (https://api.example.com).

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-secure
  annotations:
    # Enable CORS.
    nginx.ingress.kubernetes.io/enable-cors: "true"
    # Allow requests with credentials, such as cookies and Authorization headers.
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    # Specify exact origins. Do not use "*" when credentials are enabled.
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com, https://app.example.com"
    # Specify the allowed HTTP methods.
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
    # Specify the allowed request headers, including any custom headers your application requires.
    nginx.ingress.kubernetes.io/cors-allow-headers: "Content-Type, Authorization"
    # Specify which custom response headers are exposed to browser JavaScript.
    nginx.ingress.kubernetes.io/cors-expose-headers: "X-Request-ID, Content-Length, Content-Range"
    # Set the preflight cache duration in seconds. 86400 = 24 hours.
    nginx.ingress.kubernetes.io/cors-max-age: "86400"
...

Cenário B: Requisições sem credenciais

Indicado para APIs públicas e somente leitura, sem autenticação.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-public
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    # Must be "false" when cors-allow-origin is "*".
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, HEAD"
...

Verifique a configuração de CORS

Use curl para simular uma requisição preflight do navegador:

curl -i -X OPTIONS 'https://api.example.com/your/path' \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: Content-Type, Authorization'

Um preflight bem-sucedido retorna um código de status 2xx, geralmente 204 No Content ou 200 OK:

HTTP/2 204
date: Fri, 12 Sep 2025 03:51:12 GMT
access-control-allow-origin: https://example.com, https://app.example.com
access-control-allow-credentials: true
access-control-allow-methods: GET, POST, PUT, DELETE, OPTIONS
access-control-allow-headers: Content-Type, Authorization

Confirme se cada valor de access-control-allow-* corresponde à anotação nginx.ingress.kubernetes.io/cors-* equivalente no seu Ingress.

Referência de anotações de CORS

Anotação	Descrição	Cabeçalho HTTP	Exemplo
`nginx.ingress.kubernetes.io/enable-cors`	Ativa ou desativa o CORS.	N/A	`nginx.ingress.kubernetes.io/enable-cors: "true"`
`nginx.ingress.kubernetes.io/cors-allow-origin`	Origens permitidas. Separe múltiplas origens com vírgulas.	`Access-Control-Allow-Origin`	`nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Métodos HTTP permitidos.	`Access-Control-Allow-Methods`	`nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"`
`nginx.ingress.kubernetes.io/cors-allow-headers`	Cabeçalhos de requisição personalizados permitidos.	`Access-Control-Allow-Headers`	`nginx.ingress.kubernetes.io/cors-allow-headers: "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range"`
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Define se requisições com credenciais são permitidas, como cookies ou autenticação HTTP. Deve ser `"false"` quando `cors-allow-origin` for `"*"`.	`Access-Control-Allow-Credentials`	`nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
`nginx.ingress.kubernetes.io/cors-expose-headers`	Cabeçalhos de resposta expostos ao JavaScript do navegador. Por padrão, apenas cabeçalhos padrão (`Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`) ficam acessíveis. Exponha cabeçalhos personalizados como `X-Request-ID`. Requer controlador Nginx Ingress v0.44 ou posterior.	`Access-Control-Expose-Headers`	`nginx.ingress.kubernetes.io/cors-expose-headers: "Content-Length,Content-Range"`
`nginx.ingress.kubernetes.io/cors-max-age`	Tempo máximo (em segundos) que o navegador pode armazenar em cache a resposta do preflight. Valores maiores reduzem as requisições preflight; valores menores aumentam a segurança.	`Access-Control-Max-Age`	`nginx.ingress.kubernetes.io/cors-max-age: "86400"`

Perguntas frequentes

Como solucionar erros de cross-origin?

Verifique as requisições de rede nas ferramentas de desenvolvedor do navegador ou nos logs do controlador Nginx Ingress. Confirme se a origem, o método e os cabeçalhos da requisição correspondem às anotações de CORS do seu Ingress.

Mensagens de erro comuns e suas causas:

Method POST is not allowed by Access-Control-Allow-Methods in preflight response — o método não está listado em cors-allow-methods.
Access to fetch at 'https://api.example.com/data' from origin 'https://app.example.com' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: xxxx. — falha no preflight; compare os cabeçalhos de resposta access-control-allow-* com os valores das suas anotações.

Como configurar políticas de CORS diferentes para caminhos distintos no mesmo domínio?

As anotações de CORS se aplicam no nível do Ingress; a configuração por caminho não é suportada. Crie recursos de Ingress separados para grupos de caminhos que exijam políticas diferentes (por exemplo, api-public-ingress.yaml para caminhos públicos e api-private-ingress.yaml para caminhos autenticados).

Como expor cabeçalhos de resposta personalizados ao JavaScript do navegador?

Em respostas cross-origin, os navegadores só conseguem acessar estes cabeçalhos padrão: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified e Pragma. Cabeçalhos personalizados (como X-Request-ID) ficam ocultos do JavaScript, a menos que sejam explicitamente expostos.

Adicione cors-expose-headers às suas anotações para expô-los. Consulte Cenário A: Requisições com credenciais ou cookies.

Referências

Enable CORS — referência oficial de anotações do ingress-nginx
Solucionar problemas do Nginx Ingress