Konfigurasikan kebijakan CORS untuk Nginx Ingress - Container Service for Kubernetes

Browser menerapkan kebijakan asal sama (same-origin policy) yang membatasi halaman web hanya dapat mengakses sumber daya dari protokol, domain, dan port yang sama. Permintaan dari https://example.com ke https://api.example.com akan memicu error blocked by CORS policy. Tambahkan anotasi Cross-Origin Resource Sharing (CORS) pada Nginx Ingress Anda untuk mengizinkan permintaan lintas asal tertentu.

Cara kerja

CORS menangani dua jenis permintaan: simple dan preflight.

Permintaan sederhana dikirim langsung ke server:

Browser menambahkan header Origin ke permintaan—misalnya, Origin: https://example.com.
Kontroler Nginx Ingress membandingkan metode HTTP dan nilai Origin terhadap konfigurasi CORS. Jika sesuai, kontroler menambahkan header Access-Control-Allow-Origin ke respons.
Browser memeriksa apakah nilai Access-Control-Allow-Origin sesuai dengan origin permintaan. Jika sesuai, permintaan berhasil; jika header tidak ada atau nilainya tidak cocok, permintaan gagal.

Permintaan preflight mengirim pemeriksaan OPTIONS sebelum permintaan utama:

Browser mengirim permintaan OPTIONS dengan header Access-Control-Request-Method dan Access-Control-Request-Headers yang menjelaskan permintaan sebenarnya.
Jika metode atau header tidak diizinkan, preflight gagal dan permintaan utama tidak pernah dikirim. Jika preflight berhasil, permintaan utama dilanjutkan seperti permintaan simple.

Permintaan memicu preflight ketika:

Metodenya bukan GET, HEAD, atau POST.
Metodenya adalah POST dan nilai Content-Type bukan text/plain, application/x-www-form-urlencoded, atau multipart/form-data.
Permintaan menyertakan header kustom.

Penting

Saat cors-allow-credentials bernilai "true", jangan atur cors-allow-origin ke "*". Spesifikasi W3C melarang kombinasi ini: ketika permintaan membawa kredensial (seperti cookie), server harus secara eksplisit menyebutkan origin yang dipercaya. Penggunaan "*" memungkinkan situs web apa pun mengirim permintaan ber-kredensial atas nama pengguna, yang merupakan risiko keamanan.

Konfigurasikan CORS

Prasyarat

Sebelum memulai, pastikan Anda telah memiliki:

Kluster ACK dengan kontroler Nginx Ingress yang telah dideploy
Resource Ingress yang mengarahkan lalu lintas ke layanan backend Anda
Izin untuk mengedit resource Ingress di kluster

Tambahkan anotasi CORS

Masuk ke Konsol ACK. Di panel navigasi kiri, pilih Clusters.
Pada halaman Clusters, klik kluster target. Di panel navigasi kiri, pilih Network > Ingresses.
Pada halaman Ingresses, temukan Ingress target dan klik Edit YAML di kolom Actions.
Tambahkan anotasi CORS ke metadata.annotations sesuai skenario Anda.

Skenario A: Permintaan dengan kredensial atau cookie (disarankan)

Gunakan ini ketika antarmuka depan (https://example.com atau https://app.example.com) mengirim kredensial—seperti cookie atau header Authorization—ke API backend (https://api.example.com).

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-secure
  annotations:
    # Aktifkan CORS.
    nginx.ingress.kubernetes.io/enable-cors: "true"
    # Izinkan permintaan dengan kredensial, seperti cookie dan header Authorization.
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    # Tentukan origin secara eksplisit. Jangan gunakan "*" saat kredensial diaktifkan.
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com, https://app.example.com"
    # Tentukan metode HTTP yang diizinkan.
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
    # Tentukan header permintaan yang diizinkan, termasuk header kustom yang dibutuhkan aplikasi Anda.
    nginx.ingress.kubernetes.io/cors-allow-headers: "Content-Type, Authorization"
    # Tentukan header respons kustom mana yang diekspos ke JavaScript browser.
    nginx.ingress.kubernetes.io/cors-expose-headers: "X-Request-ID, Content-Length, Content-Range"
    # Atur durasi cache preflight dalam detik. 86400 = 24 jam.
    nginx.ingress.kubernetes.io/cors-max-age: "86400"
...

Skenario B: Permintaan tanpa kredensial

Gunakan ini untuk API publik yang read-only tanpa autentikasi.

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: "*"
    # Harus "false" saat cors-allow-origin adalah "*".
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, HEAD"
...

Verifikasi konfigurasi CORS

Gunakan curl untuk mensimulasikan permintaan preflight browser:

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'

Preflight yang berhasil mengembalikan kode status 2xx, biasanya 204 No Content atau 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

Pastikan setiap nilai access-control-allow-* sesuai dengan anotasi nginx.ingress.kubernetes.io/cors-* yang sesuai di Ingress Anda.

Referensi anotasi CORS

Anotasi	Deskripsi	Header HTTP	Contoh
`nginx.ingress.kubernetes.io/enable-cors`	Mengaktifkan atau menonaktifkan CORS.	N/A	`nginx.ingress.kubernetes.io/enable-cors: "true"`
`nginx.ingress.kubernetes.io/cors-allow-origin`	Origin yang diizinkan. Pisahkan beberapa origin dengan koma.	`Access-Control-Allow-Origin`	`nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Metode HTTP yang diizinkan.	`Access-Control-Allow-Methods`	`nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"`
`nginx.ingress.kubernetes.io/cors-allow-headers`	Header permintaan kustom yang diizinkan.	`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`	Menentukan apakah permintaan dengan kredensial—seperti cookie atau autentikasi HTTP—diizinkan. Harus `"false"` saat `cors-allow-origin` bernilai `"*"`.	`Access-Control-Allow-Credentials`	`nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
`nginx.ingress.kubernetes.io/cors-expose-headers`	Header respons yang diekspos ke JavaScript browser. Secara default, hanya header standar (`Cache-Control`, `Content-Language`, `Content-Type`, `Expires`, `Last-Modified`, `Pragma`) yang dapat diakses. Ekspos header kustom seperti `X-Request-ID`. Memerlukan kontroler Nginx Ingress v0.44 atau lebih baru.	`Access-Control-Expose-Headers`	`nginx.ingress.kubernetes.io/cors-expose-headers: "Content-Length,Content-Range"`
`nginx.ingress.kubernetes.io/cors-max-age`	Waktu maksimum (dalam detik) browser dapat menyimpan cache respons preflight. Nilai yang lebih besar mengurangi jumlah permintaan preflight; nilai yang lebih kecil meningkatkan keamanan.	`Access-Control-Max-Age`	`nginx.ingress.kubernetes.io/cors-max-age: "86400"`

FAQ

Bagaimana cara memecahkan masalah error lintas asal?

Periksa permintaan jaringan di developer tools browser atau log kontroler Nginx Ingress. Pastikan origin, metode, dan header permintaan sesuai dengan anotasi CORS Ingress Anda.

Pesan error umum dan penyebabnya:

Method POST is not allowed by Access-Control-Allow-Methods in preflight response — metode tersebut tidak tercantum dalam 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. — preflight gagal; bandingkan header respons access-control-allow-* dengan nilai anotasi Anda.

Bagaimana cara mengonfigurasi kebijakan CORS berbeda untuk path berbeda pada domain yang sama?

Anotasi CORS berlaku di tingkat Ingress; konfigurasi tingkat path tidak didukung. Buat resource Ingress terpisah untuk kelompok path yang memerlukan kebijakan berbeda—misalnya, api-public-ingress.yaml untuk path publik dan api-private-ingress.yaml untuk path terautentikasi.

Bagaimana cara mengekspos header respons kustom ke JavaScript browser?

Pada respons lintas asal, browser hanya dapat mengakses header standar berikut: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, dan Pragma. Header kustom—seperti X-Request-ID—tidak terlihat oleh JavaScript kecuali diekspos secara eksplisit.

Tambahkan cors-expose-headers ke anotasi Anda untuk mengeksposnya. Lihat Skenario A: Permintaan dengan kredensial atau cookie.

Referensi

Enable CORS — referensi resmi anotasi ingress-nginx
Troubleshoot Nginx Ingress issues