Konfigurasikan kebijakan Berbagi Sumber Daya Lintas Asal (CORS) di NGINX Ingress Controller - Container Service for Kubernetes

Saat sebuah halaman web dari satu origin mencoba mengakses layanan di kluster Container Service for Kubernetes (ACK), same-origin policy pada browser dapat memblokir permintaan dan menghasilkan eror blocked by CORS policy. Kebijakan ini berlaku jika domain, protokol, atau port berbeda—misalnya, saat sebuah skrip di https://example.com mencoba mengakses https://api.example.com. Atasi kesalahan ini dengan menambahkan anotasi CORS ke NGINX Ingress Anda untuk mengonfigurasi origin, metode, dan header yang diizinkan secara eksplisit, daripada menggunakan pengaturan yang terlalu permisif.

Cara kerjanya

CORS mendefinisikan dua jenis permintaan: simple dan preflighted. Browser mengirimkan permintaan simple langsung ke server. Sebaliknya, untuk permintaan preflighted, browser harus terlebih dahulu mengirimkan permintaan OPTIONS terlebih awal. Preflight ini berfungsi sebagai pemeriksaan untuk memastikan server akan menerima permintaan yang sesungguhnya sebelum dikirimkan.

Sebuah permintaan dianggap preflighted jika salah satu kondisi berikut terpenuhi:

Menggunakan metode selain GET, HEAD, atau POST.
Merupakan permintaan POST dengan Content-Type selain text/plain, application/x-www-form-urlencoded, atau multipart/form-data.
Berisi header kustom.

Ketika browser mengirim permintaan simple ke NGINX Ingress:

Browser menambahkan header Origin ke permintaan, yang menunjukkan asalnya (misalnya, Origin: https://example.com).
Controller NGINX Ingress membandingkan metode HTTP dan nilai header Origin pada permintaan dengan konfigurasi CORS. Jika cocok, controller akan menyertakan header Access-Control-Allow-Origin dalam respons, dengan nilai yang mencerminkan header Origin dari permintaan.
Browser menerima respons dan memeriksa apakah nilai header Access-Control-Allow-Origin sesuai dengan origin halaman. Jika sesuai, permintaan berhasil. Namun, jika tidak sesuai atau header tersebut tidak ada, browser akan memblokir permintaan tersebut.

Permintaan preflighted mengikuti langkah-langkah berikut sebelum permintaan utama dikirimkan:

Browser mengirimkan permintaan OPTIONS yang berisi metode (Access-Control-Request-Method) dan header (Access-Control-Request-Headers) untuk permintaan utama yang dituju.
NGINX Ingress memeriksa apakah konfigurasi CORS mengizinkan metode dan header pada permintaan OPTIONS. Jika metode yang diminta atau salah satu header tidak ada dalam daftar nilai yang diizinkan, permintaan preflight akan gagal, dan browser tidak akan mengirimkan permintaan utama.

Prosedur

Langkah 1: Konfigurasikan CORS

Masuk ke Konsol ACK. Di panel navigasi sebelah kiri, pilih Clusters.
Di halaman Clusters, klik nama kluster. Di panel navigasi di sebelah kiri, pilih Network > Ingresses.
Di halaman Ingresses, temukan Ingress yang sesuai dan klik Edit YAML di kolom Actions.
Konfigurasikan NGINX Ingress berdasarkan kasus penggunaan Anda. Untuk informasi lebih lanjut, lihat Annotations CORS umum di NGINX Ingress Controller.

Permintaan lintas origin dengan kredensial

Skenario ini berlaku untuk kasus umum pemisahan frontend-backend, di mana aplikasi frontend (https://example.com atau https://app.example.com) perlu mengakses API backend (https://api.example.com) menggunakan kredensial, seperti cookie atau header Authorization.

Tambahkan annotations berikut ke file YAML Ingress Anda. Contoh ini mengaktifkan akses lintas origin untuk metode GET, POST, dan lainnya dari origin https://example.com dan https://app.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 authorization header.
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    # Tentukan domain origin yang diizinkan untuk permintaan lintas origin. Jangan gunakan "*" dalam mode kredensial.
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com, https://app.example.com"
    # Metode HTTP yang diizinkan.
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
    # Header permintaan yang diizinkan. Ini harus termasuk header kustom yang diperlukan oleh layanan Anda, seperti Authorization.
    nginx.ingress.kubernetes.io/cors-allow-headers: "Content-Type, Authorization"
    # Tentukan header respons kustom mana yang diekspos ke frontend.
    nginx.ingress.kubernetes.io/cors-expose-headers: "X-Request-ID, Content-Length, Content-Range" 
    # Tentukan durasi maksimum (dalam detik) untuk cache permintaan preflight (misalnya, 86400 untuk 24 jam).	
    nginx.ingress.kubernetes.io/cors-max-age: "86400"
...

Permintaan lintas origin tanpa kredensial

Skenario ini berlaku untuk permintaan publik bersifat read-only yang tidak memerlukan autentikasi.

Tambahkan konfigurasi annotations berikut ke file YAML Anda.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress-secure
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    # Jika asal adalah "*", kredensial harus "false".
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, HEAD"
...

Langkah 2: Verifikasi konfigurasi CORS

Gunakan curl untuk menyimulasikan permintaan preflight OPTIONS dari 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'

Output yang diharapkan: Permintaan yang berhasil akan mengembalikan kode status 2xx, umumnya 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

Verifikasi bahwa header access-control-allow-* dalam respons sesuai dengan anotasi nginx.ingress.kubernetes.io/cors-* di sumber daya Ingress Anda.

Anotasi CORS umum di NGINX Ingress Controller

Anotasi	Deskripsi	Header HTTP terkait	Contoh
`nginx.ingress.kubernetes.io/enable-cors`	Menentukan apakah kebijakan CORS diaktifkan.		`nginx.ingress.kubernetes.io/enable-cors: "true"`
`nginx.ingress.kubernetes.io/cors-allow-origin`	Menentukan origin yang dapat mengakses sumber daya. Anda dapat mencantumkan beberapa domain yang dipisahkan koma.	Access-Control-Allow-Origin	`nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Menentukan metode HTTP yang diizinkan, seperti `GET`, `POST`, dan `PUT`.	Access-Control-Allow-Methods	`nginx.ingress.kubernetes.io/cors-allow-methods: "GET, PUT, POST, DELETE, PATCH, OPTIONS"`
`nginx.ingress.kubernetes.io/cors-allow-headers`	Menentukan 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 dapat dikirim dengan kredensial, seperti cookie atau autentikasi HTTP.	Access-Control-Allow-Credentials	`nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`
`nginx.ingress.kubernetes.io/cors-expose-headers`	Menentukan header respons mana yang dapat diakses oleh browser. Anotasi ini memerlukan NGINX Ingress Controller 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`	Durasi maksimum (dalam detik) bagi browser untuk menyimpan cache dari respons preflight. Durasi yang lebih lama mengurangi permintaan preflight. Untuk persyaratan keamanan yang tinggi, pertimbangkan nilai yang lebih rendah.	Access-Control-Max-Age	`nginx.ingress.kubernetes.io/cors-max-age: "86400"`

FAQ

Mengapa saya masih menerima kesalahan lintas origin setelah mengonfigurasi CORS?

Periksa permintaan jaringan di developer tools browser Anda atau log dari NGINX Ingress Controller. Pastikan origin, metode, dan header permintaan semuanya diizinkan oleh konfigurasi CORS di Ingress Anda.

Berikut adalah pesan kesalahan CORS yang umum. Pada kasus ini, permintaan menggunakan metode POST, tetapi metode POST tidak termasuk dalam header Access-Control-Allow-Methods pada respons preflight.

Method POST is not allowed by Access-Control-Allow-Methods in preflight response
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.

Jika `nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`, dapatkah `nginx.ingress.kubernetes.io/cors-allow-origin` diatur ke `"*"`?

Tidak. Ini adalah batasan keamanan yang diberlakukan oleh browser. Ketika sebuah permintaan berisi kredensial (seperti cookie), server harus menentukan origin tepercaya secara eksplisit dan tidak boleh menggunakan wildcard (*). Kebijakan ini mencegah situs web berbahaya menyalahgunakan kredensial pengguna untuk membuat permintaan yang tidak sah ke server Anda.

Bagaimana cara menerapkan kebijakan CORS yang berbeda untuk jalur yang berbeda dalam domain yang sama, seperti `/api/public/` dan `/api/private/`?

Anotasi CORS pada sumber daya Ingress berlaku untuk semua jalur yang didefinisikan di dalamnya. Untuk menerapkan kebijakan yang berbeda untuk jalur yang berbeda, Anda harus membuat sumber daya Ingress terpisah untuk setiap grup jalur dan menerapkan anotasi CORS yang diinginkan pada setiap sumber daya. Misalnya, buat api-public-ingress.yaml dan api-private-ingress.yaml, lalu konfigurasikan anotasi CORS yang berbeda untuk masing-masing sumber daya.

Bagaimana aplikasi sisi klien mengakses header respons kustom?

Secara default, ketika memproses permintaan lintas origin, browser hanya dapat mengakses beberapa header respons standar: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, dan Pragma. Header kustom yang dikirim oleh server, seperti X-Request-ID, tidak dapat diakses oleh JavaScript pada sisi klien secara default.

Untuk mengakses header kustom, gunakan anotasi nginx.ingress.kubernetes.io/cors-expose-headers untuk header HTTP respons Access-Control-Expose-Headers. Header ini memberi tahu browser header respons non-standar mana yang dapat diakses oleh kode sisi klien. Untuk informasi lebih lanjut, lihat Permintaan lintas origin dengan Kredensial.

Referensi

Topik ini hanya menyediakan contoh anotasi CORS yang umum untuk NGINX Ingress Controller. Untuk daftar lengkap, lihat Enable CORS.
Memecahkan masalah NGINX Ingress.