Konfigurasi kebijakan CORS di NGINX Ingress Controller-ACK-Alibaba Cloud

Saat mengakses layanan di kluster ACK, Anda mungkin menemui error blocked by CORS policy karena browser menerapkan kebijakan asal sama (same-origin policy), yang hanya mengizinkan halaman web mengakses sumber daya dari protokol, domain, dan port yang sama. Misalnya, situs web di https://example.com tidak dapat langsung mengakses sumber daya dari domain berbeda seperti https://api.example.com. Anda dapat mengonfigurasi anotasi pada Nginx Ingress untuk mengaktifkan kebijakan Cross-Origin Resource Sharing (CORS) guna mengizinkan permintaan lintas asal tertentu.

Cara kerja

CORS menangani dua jenis permintaan: permintaan simple dan permintaan preflight. Permintaan simple dikirim langsung ke server, sedangkan permintaan preflight mengharuskan browser terlebih dahulu mengirim permintaan awal OPTIONS untuk memperoleh izin sebelum mengirim permintaan utama.

Permintaan dianggap sebagai permintaan preflight jika memenuhi salah satu kondisi berikut:

Permintaan menggunakan metode selain GET, HEAD, atau POST.
Permintaan menggunakan metode POST dengan nilai Content-Type yang bukan text/plain, application/x-www-form-urlencoded, atau multipart/form-data.
Permintaan menyertakan header kustom.

Saat browser mengirim permintaan simple ke Nginx Ingress, proses berikut terjadi:

Browser menambahkan header Origin ke permintaan. Header Origin berisi asal resource tersebut, misalnya Origin: https://example.com.
Kontroler Nginx Ingress membandingkan metode HTTP dan nilai header Origin dari permintaan dengan konfigurasi CORS untuk mencari kecocokan. Jika ditemukan kecocokan, kontroler menambahkan header Access-Control-Allow-Origin ke respons. Header Access-Control-Allow-Origin berisi nilai header Origin dari permintaan asli.
Browser menerima respons dan memeriksa apakah nilai Access-Control-Allow-Origin sesuai dengan asal permintaan. Jika sesuai, permintaan berhasil; jika tidak sesuai atau respons tidak menyertakan header Access-Control-Allow-Origin, permintaan gagal.

Permintaan preflight menjalani langkah-langkah berikut terlebih dahulu. Jika berhasil, permintaan dilanjutkan seperti permintaan simple:

Browser mengirim permintaan OPTIONS yang mencakup metode (Access-Control-Request-Method) dan header (Access-Control-Request-Headers) dari permintaan sebenarnya.
Jika metode atau header dalam permintaan preflight tidak diizinkan, permintaan gagal dan permintaan utama tidak dikirim.

Prosedur

Langkah 1: Konfigurasi CORS

Masuk ke ACK console. Di panel navigasi kiri, pilih Clusters.
Pada halaman Clusters, klik nama kluster target. Di panel navigasi kiri, pilih Network > Ingresses.
Di halaman Ingresses, cari Ingress target lalu klik Edit YAML di kolom Actions.
Konfigurasikan Nginx Ingress sesuai kasus penggunaan Anda. Untuk informasi tentang konfigurasi umum, lihat Anotasi CORS Nginx Ingress umum.

Permintaan dengan kredensial atau cookie

Skema ini berlaku untuk skenario umum pemisahan antarmuka depan dan backend: aplikasi antarmuka depan (https://example.com atau https://app.example.com) perlu menyertakan kredensial—seperti cookie atau header permintaan Authorization—untuk mengakses API backend (https://api.example.com).

Tambahkan konfigurasi annotations seperti pada contoh berikut ke file YAML Anda. Contoh ini mengaktifkan akses lintas asal untuk metode seperti GET dan POST dari asal example.com dan 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 header Authorization.
    nginx.ingress.kubernetes.io/cors-allow-credentials: "true"
    # Tentukan asal yang diizinkan secara eksplisit untuk membuat permintaan lintas asal. Jangan gunakan "*" dalam mode berbasis kredensial.
    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. Anda harus menyertakan header kustom apa pun yang dibutuhkan oleh aplikasi Anda, seperti Authorization.
    nginx.ingress.kubernetes.io/cors-allow-headers: "Content-Type, Authorization"
    # Tentukan header respons kustom mana yang diekspos ke browser.
    nginx.ingress.kubernetes.io/cors-expose-headers: "X-Request-ID, Content-Length, Content-Range" 
    # Atur durasi cache maksimum untuk permintaan preflight dalam detik. Nilai contoh adalah 86400, yaitu 24 jam.
    nginx.ingress.kubernetes.io/cors-max-age: "86400"
...

Permintaan tanpa kredensial

Skema ini berlaku untuk permintaan publik read-only yang tidak memerlukan otentikasi.

Pada YAML, tambahkan konfigurasi annotations berikut.

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: "*"
    # Saat cors-allow-origin adalah "*", cors-allow-credentials harus bernilai "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 mensimulasikan browser yang mengirim permintaan preflight OPTIONS.

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 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

Periksa apakah nilai access-control-allow-* pada header respons sesuai dengan nilai nginx.ingress.kubernetes.io/cors-* yang dikonfigurasi pada resource Ingress.

Anotasi CORS Nginx Ingress umum

Anotasi	Deskripsi	Header HTTP terkait	Contoh
`nginx.ingress.kubernetes.io/enable-cors`	Menentukan apakah CORS diaktifkan.	N/A	`nginx.ingress.kubernetes.io/enable-cors: "true"`
`nginx.ingress.kubernetes.io/cors-allow-origin`	Menentukan asal yang diizinkan mengakses resource. Pisahkan beberapa asal dengan koma.	Access-Control-Allow-Origin	`nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Menentukan metode 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 dengan kredensial, seperti cookie atau informasi autentikasi HTTP, diizinkan.	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 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`	Durasi maksimum, dalam detik, yang dapat digunakan browser untuk menyimpan cache respons preflight. Durasi cache yang lebih lama mengurangi jumlah permintaan preflight. Untuk keamanan yang lebih ketat, Anda dapat menggunakan nilai yang lebih rendah.	Access-Control-Max-Age	`nginx.ingress.kubernetes.io/cors-max-age: "86400"`

FAQ

Pemecahan masalah error lintas asal

Periksa permintaan jaringan di developer tools browser atau log kontroler Nginx Ingress. Pastikan asal, metode, dan header permintaan diizinkan oleh konfigurasi CORS Ingress Anda.

Contoh berikut menunjukkan output error lintas asal yang umum. Permintaan menggunakan metode POST, tetapi metode ini tidak diizinkan dalam header respons Access-Control-Allow-Methods.

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.

Setelah mengatur `nginx.ingress.kubernetes.io/cors-allow-credentials: "true"`, apakah `nginx.ingress.kubernetes.io/cors-allow-origin` dapat dikonfigurasi sebagai `"*"`?

Tidak. Hal ini diatur oleh spesifikasi W3C dan kebijakan keamanan browser. Saat permintaan perlu membawa kredensial (seperti cookie), server harus secara eksplisit menentukan asal yang dipercaya dan tidak boleh menggunakan wildcard *. Langkah ini bertujuan mencegah situs web berbahaya menggunakan kredensial login pengguna untuk mengirim permintaan ke server, sehingga menghindari risiko keamanan potensial.

Untuk path berbeda pada domain yang sama (seperti `/api/public/` dan `/api/private/`), bagaimana cara mengonfigurasi kebijakan CORS yang berbeda?

Pada Nginx Ingress, anotasi CORS diterapkan pada tingkat resource Ingress, dan konfigurasi berbasis path tidak didukung. Praktik standar adalah membuat resource Ingress terpisah untuk kelompok path yang memerlukan kebijakan CORS berbeda. Misalnya, buat api-public-ingress.yaml dan api-private-ingress.yaml, lalu atur anotasi CORS berbeda untuk masing-masing.

Mengakses header respons kustom

Secara default, saat menangani permintaan lintas asal, browser hanya dapat mengakses header respons standar, termasuk Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, dan Pragma. Setiap header respons kustom yang dikembalikan oleh server, seperti X-Request-ID, tidak terlihat oleh JavaScript sisi klien tanpa konfigurasi tambahan.

Anotasi nginx.ingress.kubernetes.io/cors-expose-headers digunakan untuk mengatur header respons HTTP Access-Control-Expose-Headers, yang menentukan header respons non-standar mana yang dapat diakses oleh kode JavaScript sisi klien. Untuk konfigurasi spesifik, lihat Skema lintas asal dengan kredensial atau cookie.

Referensi

Topik ini hanya mencakup anotasi CORS umum untuk kontroler Nginx Ingress. Untuk informasi lebih lanjut, lihat dokumentasi resmi Enable CORS.
Pemecahan masalah isu Nginx Ingress.