Container Service for Kubernetes：Kamus Konfigurasi NGINX Ingress

Daftar isi

Konfigurasi default ConfigMap

Untuk memodifikasi konfigurasi ConfigMap yang digunakan oleh NGINX Ingress, jalankan perintah kubectl edit cm -n kube-system nginx-configuration. Blok kode sampel berikut menyediakan konfigurasi default dari ConfigMap. Untuk informasi lebih lanjut, lihat Dokumentasi Resmi.

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-configuration
 namespace: <Namespace>  # Nilai default: kube-system.
 labels:
   app: ingress-nginx
data:
   log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
   proxy-body-size: 20m
   proxy-connect-timeout: "10"
   max-worker-connections: "65536"
   enable-underscores-in-headers: "true"
   reuse-port: "true"
   worker-cpu-affinity: "auto"
   server-tokens: "false"
   ssl-redirect: "false"
   allow-backend-server-header: "true"
   ignore-invalid-headers: "true"
   generate-request-id: "true"
   upstream-keepalive-timeout: "900"

Tabel berikut menjelaskan bidang dalam blok kode sebelumnya.

Ingress anotasi

Saat menggunakan controller NGINX Ingress, Anda dapat memodifikasi konfigurasi controller untuk memenuhi kebutuhan bisnis Anda. Untuk mengontrol perilaku NGINX, Anda dapat menambahkan anotasi ke NGINX Ingress. Tabel berikut menjelaskan anotasi NGINX Ingress umum. Untuk informasi lebih lanjut, lihat Anotasi NGINX Ingress.

Algoritma penyeimbangan beban

NGINX Ingress menyediakan berbagai algoritma penyeimbangan beban untuk mengoptimalkan distribusi lalu lintas di antara layanan backend. Anda dapat memilih algoritma penyeimbangan beban berdasarkan fitur dan persyaratan aplikasi Anda.

Blok YAML sampel berikut memberikan contoh tentang cara mengonfigurasi penghashan konsisten untuk penyeimbangan beban.

apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Gunakan Uniform Resource Identifier (URI) dari permintaan untuk hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Gunakan URI dan nama domain dari permintaan untuk hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Gunakan URI dari permintaan dan nilai teks kustom untuk hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              service:
                name: <YOUR_SERVICE_NAME>  # Ganti nilai dengan nama Service aktual.
                port:
                  number: <YOUR_SERVICE_PORT>  # Ganti nilai dengan port Service aktual.
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # Gunakan URI dari permintaan untuk hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # Gunakan URI dan nama domain dari permintaan untuk hashing. 
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # Gunakan URI dari permintaan dan nilai teks kustom untuk hashing. 
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              serviceName: <YOUR_SERVICE_NAME>  # Ganti nilai dengan nama Service aktual.
              servicePort: <YOUR_SERVICE_PORT>  # Ganti nilai dengan port Service aktual.

Afinasi cookie

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi afinasi sesi berbasis cookie.

Blok YAML sampel berikut memberikan contoh tentang cara mengonfigurasi afinasi berbasis cookie:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
    nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
spec:
  ingressClassName: nginx
  rules:
  - host: stickyingress.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port: 
              number: 80

Pengalihan

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi pengalihan untuk NGINX Ingress.

Konfigurasi Ingress sampel berikut menunjukkan cara menentukan URL tujuan untuk pengalihan permanen. Setelah Anda menerapkan aturan Ingress, permintaan ke foo.com akan dialihkan ke bar.com.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
  - host: foo.com
    http:
      paths:
      - path: "/"
        pathType: ImplementationSpecific
        backend:
         service:
            name: httpbin
            port:
              number: 8000

Penulisan ulang

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi penulisan ulang untuk NGINX Ingress.

Konfigurasi Ingress sampel berikut menunjukkan cara mengonfigurasi penulisan ulang host. Setelah Anda menerapkan aturan Ingress, sistem akan menulis ulang nama host dari permintaan ke example.com/test sebagai test.com/test.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: ImplementationSpecific

Pembatasan laju

Untuk memastikan stabilitas layanan, Anda dapat mengonfigurasi kebijakan pembatasan laju untuk mengontrol frekuensi dan konkurensi permintaan yang dikirim dari setiap alamat IP klien. Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi pembatasan laju.

Konfigurasi Ingress sampel berikut menunjukkan cara mengonfigurasi pembatasan laju:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: 100K
    nginx.ingress.kubernetes.io/limit-whitelist: 10.1.10.100
    nginx.ingress.kubernetes.io/limit-rps: 1
    nginx.ingress.kubernetes.io/limit-rpm: 30
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-backend-svc
          servicePort: 80

Fallback

Untuk memastikan ketersediaan tinggi dan stabilitas layanan Anda, NGINX Ingress menyediakan konfigurasi pemulihan bencana (fallback) untuk memungkinkan Anda menyelesaikan masalah seperti ketidaktersediaan node dan kesalahan tertentu. Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi pemulihan bencana.

Rilis canary

Rilis canary dan penerapan biru-hijau banyak digunakan untuk memastikan peningkatan aplikasi yang mulus dan ketersediaan tinggi. Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi kontrol lalu lintas fleksibel untuk memenuhi berbagai persyaratan untuk rilis layanan. Untuk informasi lebih lanjut, lihat Gunakan Controller NGINX Ingress untuk Menerapkan Rilis Canary dan Biru-Hijau.

Batas waktu

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi batas waktu untuk NGINX Ingress, termasuk pengaturan batas waktu global dan pengaturan batas waktu kustom untuk sumber daya tertentu. Pengaturan batas waktu yang tepat dapat mengoptimalkan kinerja dan keandalan koneksi.

• Pengaturan Batas Waktu Global

  Anda dapat menjalankan perintah kubectl edit cm -n kube-system nginx-configuration untuk mengonfigurasi bidang berikut untuk pengaturan batas waktu global.

  Opsi konfigurasi	Deskripsi	Nilai default
  proxy-connect-timeout	Menetapkan periode timeout untuk membangun koneksi dengan server proxy. Secara umum, nilainya tidak boleh melebihi 75 detik.	5 detik
  proxy-read-timeout	Menetapkan periode timeout untuk membaca respons dari server proxy. Periode timeout ini berlaku antara dua operasi baca berturut-turut, bukan untuk transmisi seluruh respons.	60 detik
  proxy-send-timeout	Menetapkan periode timeout untuk mengirim permintaan ke server proxy. Periode timeout ini berlaku antara dua operasi tulis berturut-turut, bukan untuk transmisi seluruh permintaan.	60 detik
  proxy-stream-next-upstream-timeout	Membatasi jumlah waktu yang diizinkan untuk meneruskan koneksi ke server berikutnya. Jika Anda menetapkan nilainya menjadi 0, tidak ada batasan yang diberlakukan.	600 detik
  proxy-stream-timeout	Menetapkan periode timeout antara dua operasi baca atau tulis berturut-turut pada koneksi klien atau server proxy. Jika tidak ada data yang ditransmisikan dalam periode tersebut, koneksi ditutup.	600 detik
  upstream-keepalive-timeout	Menetapkan periode timeout untuk menjaga koneksi idle tetap terbuka dengan server upstream.	Edition open source: 60 detik Edition ACK: 900 detik
  worker-shutdown-timeout	Menetapkan periode timeout untuk shutdown yang aman.	240 detik
  proxy-protocol-header-timeout	Menetapkan periode timeout untuk menerima header protokol proxy. Nilai default mencegah handler Transport Layer Security (TLS) passthrough menunggu tanpa batas untuk koneksi yang rusak.	5 detik
  ssl-session-timeout	Menetapkan periode validitas untuk parameter sesi SSL di cache sesi. Waktu kedaluwarsa bergantung pada waktu pembuatan. Setiap cache sesi menempati sekitar 0,25 MB ruang.	10 menit
  client-body-timeout	Menetapkan periode timeout untuk membaca badan permintaan klien.	60 detik
  client-header-timeout	Menetapkan periode timeout untuk membaca header permintaan klien.	60 detik

• Pengaturan Batas Waktu Kustom pada Sumber Daya Tertentu

  Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi pengaturan batas waktu untuk sumber daya tertentu.

  Anotasi	Deskripsi
  nginx.ingress.kubernetes.io/proxy-connect-timeout	Menetapkan periode timeout untuk membangun koneksi dengan server proxy.
  nginx.ingress.kubernetes.io/proxy-send-timeout	Menetapkan periode timeout untuk mengirim data ke server proxy.
  nginx.ingress.kubernetes.io/proxy-read-timeout	Menetapkan periode timeout untuk membaca data dari server proxy.
  nginx.ingress.kubernetes.io/proxy-request-buffering	Menentukan apakah akan mengaktifkan fitur penyanggaan permintaan. Nilai valid: on: mengaktifkan penyanggaan permintaan. Setelah penyanggaan permintaan diaktifkan, data permintaan hanya diteruskan ke workload backend setelah sepenuhnya diterima. Permintaan yang dikodekan chunked HTTP/1.1 tidak tunduk pada pengaturan ini dan selalu disimpan dalam buffer. off: menonaktifkan penyanggaan permintaan. Setelah penyanggaan permintaan dinonaktifkan, jika terjadi kesalahan selama transmisi data, tidak ada workload yang dipilih untuk percobaan ulang.

CORS

Setelah Anda mengonfigurasi berbagi sumber daya lintas domain (CORS) untuk controller NGINX Ingress, Anda dapat mengizinkan sumber daya tertentu diakses lintas domain. Untuk informasi lebih lanjut, lihat Konfigurasikan CORS pada NGINX Ingress.

Kebijakan pengulangan

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi kebijakan pengulangan. Pengulangan dapat meningkatkan ketersediaan dan toleransi kesalahan aplikasi Anda.

Kontrol akses berbasis alamat IP

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi daftar putih dan daftar hitam IP untuk NGINX Ingress.

Konfigurasi Ingress sampel berikut menunjukkan cara mengonfigurasi daftar putih IP:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: 10.1.10.2
spec:
  rules:
  - host: iphone.exmaple.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-example-svc
          servicePort: 80

Untuk mengonfigurasi pengaturan global, jalankan perintah kubectl edit cm -n kube-system nginx-configuration dan ubah bidang whitelist-source-range.

Pemantulan trafik

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi pemantulan trafik. Pemantulan trafik membantu Anda mendeteksi risiko potensial tanpa mengganggu layanan Anda di lingkungan produksi dan meningkatkan stabilitas aplikasi. Untuk informasi lebih lanjut, lihat Gunakan Controller Ingress untuk Memantulkan Lalu Lintas Jaringan.

Perlindungan keamanan

Anda dapat mengonfigurasi perlindungan keamanan untuk mengamankan komunikasi antara klien dan gateway. Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengenkripsi komunikasi. Untuk informasi lebih lanjut, lihat Enkripsi Controller NGINX Ingress.

• Komunikasi Terenkripsi Antara Klien dan Gateway

  Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengenkripsi komunikasi antara klien dan gateway.

  Anotasi	Ruang lingkup	Deskripsi
  nginx.ingress.kubernetes.io/ssl-cipher	Nama domain	Menentukan paket cipher TLS. Anda dapat menentukan beberapa paket cipher TLS, yang dipisahkan oleh koma (,). Parameter ini hanya berlaku jika versi TLS dari 1.0 hingga 1.2 digunakan selama jabat tangan TLS. Paket cipher default: ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
  nginx.ingress.kubernetes.io/auth-tls-secret	Nama domain	Menentukan sertifikat otoritas sertifikat (CA) yang digunakan oleh gateway untuk memverifikasi sertifikat yang diberikan oleh klien selama jabat tangan mutual TLS (mTLS). Anotasi ini cocok untuk skenario di mana gateway perlu memverifikasi identitas klien. Secret yang sesuai harus mencakup file bernama ca.crt. File ca.crt berisi rantai CA lengkap.

• Komunikasi Terenkripsi Antara Gateway dan Layanan Backend

  Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengenkripsi komunikasi antara layanan backend dan gateway.

  Anotasi	Ruang lingkup	Deskripsi
  nginx.ingress.kubernetes.io/proxy-ssl-secret	Layanan	Menentukan sertifikat klien yang digunakan oleh gateway. Sertifikat klien digunakan oleh layanan backend untuk mengotentikasi gateway. Sertifikat yang ditentukan harus dalam format Privacy Enhanced Mail (PEM). Secret harus mencakup file berikut: tls.crt: sertifikat klien. tls.key: kunci privat dari sertifikat klien. ca.crt: sertifikat CA tepercaya yang digunakan untuk mengotentikasi server HTTPS proxy. Nilainya harus dalam format "namespace/secretName".
  nginx.ingress.kubernetes.io/proxy-ssl-name	Layanan	Menentukan Server Name Indication (SNI) yang digunakan selama jabat tangan TLS.
  nginx.ingress.kubernetes.io/proxy-ssl-server-name	Layanan	Menentukan apakah akan mengaktifkan atau menonaktifkan SNI yang digunakan selama jabat tangan TLS.

Otentikasi keamanan

Tabel berikut menjelaskan anotasi yang dapat Anda gunakan untuk mengonfigurasi Otentikasi Dasar untuk memungkinkan hanya pengguna yang berwenang mengakses aplikasi Anda.

Prosedur:

1. Gunakan alat baris perintah htpasswd untuk menghasilkan file kata sandi.

   htpasswd -c auth joker

   Lihat file kata sandi.

   cat auth 
   # Keluaran yang diharapkan: joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

2. Buat Secret berdasarkan file kata sandi:

   kubectl create secret generic basic-auth --from-file=auth 

3. Aktifkan Otentikasi Dasar dalam konfigurasi Ingress. Contoh:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-nginx
     annotations:
       kubernetes.io/ingress.class: "nginx"
       nginx.ingress.kubernetes.io/auth-type: basic
       nginx.ingress.kubernetes.io/auth-secret: basic-auth
   spec:
     rules:
     - host: iphone.example.com 
       http:
         paths:
         - path: 
           backend:
             serviceName: iphone-backend-svc
             servicePort: 80